0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 C-language API
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 e. This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 ve source.** on
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 this file under
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 hanges its name
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 ude <stdarg.h>
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 the definition
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 e can call this
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51 ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 o mark those.**
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 ther deprecated
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 use deprecated
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 y. Application
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 e aware that.**
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a ed. But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 t and gone back
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 RIMENTAL../*.**
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 _NUMBER.# undef
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
0ae0: 72 73 20 7b 48 31 30 30 31 30 7d 20 3c 53 36 30 rs {H10010} <S60
0af0: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 100>.**.** The S
0b00: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e QLITE_VERSION an
0b10: 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e d SQLITE_VERSION
0b20: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73 _NUMBER #defines
0b30: 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 in.** the sqlit
0b40: 65 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66 e3.h file specif
0b50: 79 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 y the version of
0b60: 20 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69 SQLite with whi
0b70: 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65 ch.** that heade
0b80: 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69 r file is associ
0b90: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ated..**.** The
0ba0: 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c "version" of SQL
0bb0: 69 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 ite is a string
0bc0: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 57 2e 58 of the form "W.X
0bd0: 2e 59 22 20 6f 72 20 22 57 2e 58 2e 59 2e 5a 22 .Y" or "W.X.Y.Z"
0be0: 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61 6c 75 65 ..** The W value
0bf0: 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f is major versio
0c00: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20 n number and is
0c10: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 always 3 in SQLi
0c20: 74 65 33 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61 te3..** The W va
0c30: 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 lue only changes
0c40: 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20 when backwards
0c50: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 compatibility is
0c60: 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 .** broken and w
0c70: 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 e intend to neve
0c80: 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64 r break backward
0c90: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
0ca0: 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 .** The X value
0cb0: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 is the minor ver
0cc0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 sion number and
0cd0: 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 only changes whe
0ce0: 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d n.** there are m
0cf0: 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 ajor feature enh
0d00: 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 ancements that a
0d10: 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 re forwards comp
0d20: 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f atible.** but no
0d30: 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 t backwards comp
0d40: 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 59 atible..** The Y
0d50: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65 value is the re
0d60: 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64 lease number and
0d70: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 is incremented
0d80: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c with.** each rel
0d90: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 ease but resets
0da0: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76 back to 0 whenev
0db0: 65 72 20 58 20 69 73 20 69 6e 63 72 65 6d 65 6e er X is incremen
0dc0: 74 65 64 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61 ted..** The Z va
0dd0: 6c 75 65 20 6f 6e 6c 79 20 61 70 70 65 61 72 73 lue only appears
0de0: 20 6f 6e 20 62 72 61 6e 63 68 20 72 65 6c 65 61 on branch relea
0df0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 ses..**.** The S
0e00: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0e10: 4d 42 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67 MBER is an integ
0e20: 65 72 20 74 68 61 74 20 69 73 20 63 6f 6d 70 75 er that is compu
0e30: 74 65 64 20 61 73 0a 2a 2a 20 66 6f 6c 6c 6f 77 ted as.** follow
0e40: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
0e50: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 53 51 uote><pre>.** SQ
0e60: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
0e70: 42 45 52 20 3d 20 57 2a 31 30 30 30 30 30 30 20 BER = W*1000000
0e80: 2b 20 58 2a 31 30 30 30 20 2b 20 59 0a 2a 2a 20 + X*1000 + Y.**
0e90: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
0ea0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 te>.**.** Since
0eb0: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 version 3.6.18,
0ec0: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f SQLite source co
0ed0: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 de has been stor
0ee0: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 ed in the.** <a
0ef0: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 href="http://www
0f00: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f .fossil-scm.org/
0f10: 22 3e 66 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 ">fossil configu
0f20: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e ration managemen
0f30: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e t.** system</a>.
0f40: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 The SQLITE_SOU
0f50: 52 43 45 5f 49 44 0a 2a 2a 20 6d 61 63 72 6f 20 RCE_ID.** macro
0f60: 69 73 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 is a string whic
0f70: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 h identifies a p
0f80: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d articular check-
0f90: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 in of SQLite.**
0fa0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 within its confi
0fb0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d guration managem
0fc0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 54 68 65 ent system. The
0fd0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 string contains
0fe0: 20 74 68 65 0a 2a 2a 20 64 61 74 65 20 61 6e 64 the.** date and
0ff0: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 time of the che
1000: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 ck-in (UTC) and
1010: 61 6e 20 53 48 41 31 20 68 61 73 68 20 6f 66 20 an SHA1 hash of
1020: 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 6f the entire.** so
1030: 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a urce tree..**.**
1040: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
1050: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
1060: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c ],.** [sqlite3_l
1070: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
1080: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f ()], [sqlite3_so
1090: 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 urceid()],.** [s
10a0: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d qlite_version()]
10b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 and [sqlite_sou
10c0: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a rce_id()]..**.**
10d0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
10e0: 48 31 30 30 31 31 5d 20 5b 48 31 30 30 31 34 5d H10011] [H10014]
10f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
1100: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 TE_VERSION
1110: 20 20 22 33 2e 36 2e 32 31 22 0a 23 64 65 66 69 "3.6.21".#defi
1120: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f ne SQLITE_VERSIO
1130: 4e 5f 4e 55 4d 42 45 52 20 33 30 30 36 30 32 31 N_NUMBER 3006021
1140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1150: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 SOURCE_ID "
1160: 32 30 30 39 2d 31 31 2d 32 33 20 31 33 3a 31 37 2009-11-23 13:17
1170: 3a 32 37 20 33 39 32 31 34 61 65 65 36 35 35 33 :27 39214aee6553
1180: 64 62 37 36 33 30 39 38 35 31 65 37 61 61 37 34 db76309851e7aa74
1190: 66 63 63 30 32 64 34 66 35 39 62 37 22 0a 0a 2f fcc02d4f59b7"../
11a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
11b0: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 un-Time Library
11c0: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 Version Numbers
11d0: 7b 48 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 {H10020} <S60100
11e0: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 >.** KEYWORDS: s
11f0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a qlite3_version.*
1200: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 *.** These inter
1210: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 faces provide th
1220: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 e same informati
1230: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 on as the [SQLIT
1240: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b E_VERSION],.** [
1250: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
1260: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c UMBER], and [SQL
1270: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23 ITE_SOURCE_ID] #
1280: 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 defines in the h
1290: 65 61 64 65 72 2c 0a 2a 2a 20 62 75 74 20 61 72 eader,.** but ar
12a0: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 e associated wit
12b0: 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e h the library in
12c0: 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 stead of the hea
12d0: 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 der file. Cauti
12e0: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 ous.** programme
12f0: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 rs might include
1300: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d assert() statem
1310: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 ents in their ap
1320: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 plication to.**
1330: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 verify that valu
1340: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 es returned by t
1350: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
1360: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 match the macros
1370: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 in.** the heade
1380: 72 2c 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 r, and thus insu
1390: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c re that the appl
13a0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f ication is.** co
13b0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 mpiled with matc
13c0: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 hing library and
13d0: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a header files..*
13e0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
13f0: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 ><pre>.** assert
1400: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 ( sqlite3_libver
1410: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 sion_number()==S
1420: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1430: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 MBER );.** asser
1440: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
1450: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 3_sourceid(),SQL
1460: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d ITE_SOURCE_ID)==
1470: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 0 );.** assert(
1480: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c strcmp(sqlite3_l
1490: 69 62 76 65 72 73 69 6f 6e 2c 53 51 4c 49 54 45 ibversion,SQLITE
14a0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a _VERSION)==0 );.
14b0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
14c0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
14e0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
14f0: 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 eturns the same
1500: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 information as i
1510: 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 s.** in the sqli
1520: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 te3_version[] st
1530: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 ring constant.
1540: 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 The function is
1550: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 provided.** for
1560: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 use in DLLs sinc
1570: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 e DLL users usua
1580: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 lly do not have
1590: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f direct access to
15a0: 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 string.** const
15b0: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 ants within the
15c0: 44 4c 4c 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c DLL. Similarly,
15d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 the sqlite3_sou
15e0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e rceid() function
15f0: 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 .** returns the
1600: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e same information
1610: 20 61 73 20 69 73 20 69 6e 20 74 68 65 20 5b 53 as is in the [S
1620: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d QLITE_SOURCE_ID]
1630: 20 23 64 65 66 69 6e 65 20 6f 66 0a 2a 2a 20 74 #define of.** t
1640: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a he header file..
1650: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
1660: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
1670: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
1680: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a ource_id()]..**.
1690: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
16a0: 20 5b 48 31 30 30 32 31 5d 20 5b 48 31 30 30 32 [H10021] [H1002
16b0: 32 5d 20 5b 48 31 30 30 32 33 5d 0a 2a 2f 0a 53 2] [H10023].*/.S
16c0: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
16d0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 _EXTERN const ch
16e0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 ar sqlite3_versi
16f0: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49 on[];.SQLITE_API
1700: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
1710: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1720: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
1730: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
1740: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 lite3_sourceid(v
1750: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
1760: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 int sqlite3_lib
1770: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 version_number(v
1780: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
1790: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 I3REF: Test To S
17a0: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 ee If The Librar
17b0: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 20 y Is Threadsafe
17c0: 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31 30 30 {H10100} <S60100
17d0: 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 >.**.** SQLite c
17e0: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 an be compiled w
17f0: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d ith or without m
1800: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a utexes. When.**
1810: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1820: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 EADSAFE] C prepr
1830: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 ocessor macro is
1840: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 1 or 2, mutexes
1850: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 .** are enabled
1860: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 and SQLite is th
1870: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 readsafe. When
1880: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 the.** [SQLITE_T
1890: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f HREADSAFE] macro
18a0: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d is 0, .** the m
18b0: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 utexes are omitt
18c0: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 ed. Without the
18d0: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 mutexes, it is
18e0: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 not safe.** to u
18f0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 se SQLite concur
1900: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 rently from more
1910: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 than one thread
1920: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 ..**.** Enabling
1930: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 mutexes incurs
1940: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 a measurable per
1950: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 formance penalty
1960: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 ..** So if speed
1970: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d is of utmost im
1980: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b portance, it mak
1990: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 es sense to disa
19a0: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 ble.** the mutex
19b0: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 es. But for max
19c0: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 imum safety, mut
19d0: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 exes should be e
19e0: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64 nabled..** The d
19f0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
1a00: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 is for mutexes t
1a10: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a o be enabled..**
1a20: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
1a30: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 ce can be used b
1a40: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e y an application
1a50: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
1a60: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f at the.** versio
1a70: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 n of SQLite that
1a80: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 it is linking a
1a90: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 gainst was compi
1aa0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
1ab0: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 desired setting
1ac0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
1ad0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f HREADSAFE] macro
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
1af0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f erface only repo
1b00: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 rts on the compi
1b10: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 le-time mutex se
1b20: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 tting.** of the
1b30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
1b40: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 FE] flag. If SQ
1b50: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
1b60: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f with.** SQLITE_
1b70: 54 48 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 THREADSAFE=1 the
1b80: 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e n mutexes are en
1b90: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
1ba0: 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 but.** can be f
1bb0: 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c ully or partiall
1bc0: 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 y disabled using
1bd0: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
1be0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a te3_config()].**
1bf0: 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 with the verbs
1c00: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
1c10: 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 INGLETHREAD], [S
1c20: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
1c30: 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 TITHREAD],.** or
1c40: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
1c50: 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 MUTEX]. The ret
1c60: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
1c70: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 s function shows
1c80: 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 .** only the def
1c90: 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ault compile-tim
1ca0: 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 e setting, not a
1cb0: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e ny run-time chan
1cc0: 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 ges.** to that s
1cd0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 etting..**.** Se
1ce0: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
1cf0: 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 mode] documenta
1d00: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
1d10: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
1d20: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1d30: 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20 5b 48 nts: [H10101] [H
1d40: 31 30 31 30 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 10102].*/.SQLITE
1d50: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1d60: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 _threadsafe(void
1d70: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1d80: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
1d90: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b nection Handle {
1da0: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e H12000} <S40200>
1db0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 .** KEYWORDS: {d
1dc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1dd0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f on} {database co
1de0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a nnections}.**.**
1df0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 Each open SQLit
1e00: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 e database is re
1e10: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 presented by a p
1e20: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
1e30: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 tance of.** the
1e40: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 opaque structure
1e50: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 named "sqlite3"
1e60: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 . It is useful
1e70: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 to think of an s
1e80: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 qlite3.** pointe
1e90: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 r as an object.
1ea0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 The [sqlite3_op
1eb0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
1ec0: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a open16()], and.*
1ed0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
1ee0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 v2()] interfaces
1ef0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 are its constru
1f00: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 ctors, and [sqli
1f10: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 te3_close()].**
1f20: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f is its destructo
1f30: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 r. There are ma
1f40: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 ny other interfa
1f50: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 ces (such as.**
1f60: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f70: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
1f80: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
1f90: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
1fa0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
1fb0: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 t()] to name but
1fc0: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 three) that are
1fd0: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a methods on an.*
1fe0: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 * sqlite3 object
1ff0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
2000: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 uct sqlite3 sqli
2010: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 te3;../*.** CAPI
2020: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 3REF: 64-Bit Int
2030: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32 eger Types {H102
2040: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20 00} <S10110>.**
2050: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
2060: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 _int64 sqlite_ui
2070: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 nt64.**.** Becau
2080: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 se there is no c
2090: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 ross-platform wa
20a0: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d y to specify 64-
20b0: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 bit integer type
20c0: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c s.** SQLite incl
20d0: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f udes typedefs fo
20e0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 r 64-bit signed
20f0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 and unsigned int
2100: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 egers..**.** The
2110: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 sqlite3_int64 a
2120: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 nd sqlite3_uint6
2130: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 4 are the prefer
2140: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 red type definit
2150: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c ions..** The sql
2160: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 ite_int64 and sq
2170: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 lite_uint64 type
2180: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 s are supported
2190: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a for backwards.**
21a0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f compatibility o
21b0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 nly..**.** Requi
21c0: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31 rements: [H10201
21d0: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69 ] [H10202].*/.#i
21e0: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 fdef SQLITE_INT6
21f0: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 4_TYPE. typedef
2200: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
2210: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b PE sqlite_int64;
2220: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 . typedef unsig
2230: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 ned SQLITE_INT64
2240: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e _TYPE sqlite_uin
2250: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e t64;.#elif defin
2260: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 ed(_MSC_VER) ||
2270: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e defined(__BORLAN
2280: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 DC__). typedef
2290: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 __int64 sqlite_i
22a0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
22b0: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 unsigned __int64
22c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
22d0: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 #else. typedef
22e0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 long long int sq
22f0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
2300: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c pedef unsigned l
2310: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
2320: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 ite_uint64;.#end
2330: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 if.typedef sqlit
2340: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f e_int64 sqlite3_
2350: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 int64;.typedef s
2360: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c qlite_uint64 sql
2370: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a ite3_uint64;../*
2380: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 .** If compiling
2390: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 for a processor
23a0: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 that lacks floa
23b0: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f ting point suppo
23c0: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 rt,.** substitut
23d0: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c e integer for fl
23e0: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f oating-point..*/
23f0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f .#ifdef SQLITE_O
2400: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 MIT_FLOATING_POI
2410: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 NT.# define doub
2420: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 le sqlite3_int64
2430: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
2440: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 API3REF: Closing
2450: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e A Database Conn
2460: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 ection {H12010}
2470: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e <S30100><S40200>
2480: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2490: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 ine is the destr
24a0: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 uctor for the [s
24b0: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a qlite3] object..
24c0: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
24d0: 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 33 ns must [sqlite3
24e0: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 _finalize | fina
24f0: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 lize] all [prepa
2500: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a red statements].
2510: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
2520: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f blob_close | clo
2530: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 se] all [BLOB ha
2540: 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 ndles] associate
2550: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 d with.** the [s
2560: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 qlite3] object p
2570: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 rior to attempti
2580: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 ng to close the
2590: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 object..**.** If
25a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
25b0: 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 )] is invoked wh
25c0: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f ile a transactio
25d0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 n is open,.** th
25e0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 e transaction is
25f0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
2600: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a olled back..**.*
2610: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 * The C paramete
2620: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c r to [sqlite3_cl
2630: 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20 ose(C)] must be
2640: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a either a NULL.**
2650: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b pointer or an [
2660: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
2670: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 pointer obtained
2680: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
2690: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
26a0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f te3_open16()], o
26b0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r.** [sqlite3_op
26c0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f en_v2()], and no
26d0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f t previously clo
26e0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 sed..**.** Requi
26f0: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
2700: 30 31 31 5d 20 5b 48 31 32 30 31 32 5d 20 5b 48 011] [H12012] [H
2710: 31 32 30 31 33 5d 20 5b 48 31 32 30 31 34 5d 20 12013] [H12014]
2720: 5b 48 31 32 30 31 35 5d 20 5b 48 31 32 30 31 39 [H12015] [H12019
2730: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
2740: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 int sqlite3_clos
2750: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f e(sqlite3 *);../
2760: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f *.** The type fo
2770: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e r a callback fun
2780: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 ction..** This i
2790: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 s legacy and dep
27a0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 recated. It is
27b0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 included for his
27c0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 torical.** compa
27d0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 tibility and is
27e0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a not documented..
27f0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 */.typedef int (
2800: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 *sqlite3_callbac
2810: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
2820: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f r**, char**);../
2830: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
2840: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 ne-Step Query Ex
2850: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 ecution Interfac
2860: 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 e {H12100} <S100
2870: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
2880: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 lite3_exec() int
2890: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 erface is a conv
28a0: 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 enient way of ru
28b0: 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 nning one or mor
28c0: 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 e.** SQL stateme
28d0: 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 nts without havi
28e0: 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f ng to write a lo
28f0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 t of C code. Th
2900: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a e UTF-8 encoded.
2910: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
2920: 73 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 s are passed in
2930: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
2940: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2950: 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 e3_exec()..** Th
2960: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 e statements are
2970: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 evaluated one b
2980: 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 y one until eith
2990: 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a er an error or.*
29a0: 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 * an interrupt i
29b0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f s encountered, o
29c0: 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 r until they are
29d0: 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 all done. The
29e0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 3rd parameter.**
29f0: 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 is an optional
2a00: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 callback that is
2a10: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f invoked once fo
2a20: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e r each row of an
2a30: 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c y query.** resul
2a40: 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 ts produced by t
2a50: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
2a60: 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 s. The 5th para
2a70: 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 meter tells wher
2a80: 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e e.** to write an
2a90: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 y error messages
2aa0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f ..**.** The erro
2ab0: 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 r message passed
2ac0: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 back through th
2ad0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
2ae0: 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 is held.** in me
2af0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
2b00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
2b10: 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 oc()]. To avoid
2b20: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a a memory leak,.
2b30: 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 ** the calling a
2b40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
2b50: 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f d call [sqlite3_
2b60: 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 free()] on any e
2b70: 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
2b80: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 returned through
2b90: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
2ba0: 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 er when it has f
2bb0: 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a inished using.**
2bc0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
2bd0: 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ge..**.** If the
2be0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
2bf0: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 n the 2nd parame
2c00: 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 ter is NULL or a
2c10: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a n empty string.*
2c20: 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f * or a string co
2c30: 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 ntaining only wh
2c40: 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d itespace and com
2c50: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 ments, then no S
2c60: 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 QL.** statements
2c70: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 are evaluated a
2c80: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 nd the database
2c90: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a is not changed..
2ca0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
2cb0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
2cc0: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 ce is implemente
2cd0: 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a d in terms of.**
2ce0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2cf0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
2d00: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 3_step()], and [
2d10: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2d20: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ()]..** The sqli
2d30: 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 te3_exec() routi
2d40: 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 ne does nothing
2d50: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
2d60: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 that cannot be d
2d70: 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 one.** by [sqlit
2d80: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2d90: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
2da0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
2db0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
2dc0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
2dd0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2de0: 74 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 te3_exec()] must
2df0: 20 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 be an valid and
2e00: 20 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 open.** [databa
2e10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
2e20: 2a 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 **.** The databa
2e30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 se connection mu
2e40: 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 st not be closed
2e50: 20 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 while.** [sqlit
2e60: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 e3_exec()] is ru
2e70: 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 nning..**.** The
2e80: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
2e90: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 n should use [sq
2ea0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f lite3_free()] to
2eb0: 20 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d free.** the mem
2ec0: 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 ory that *errmsg
2ed0: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
2ee0: 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 g at once the er
2ef0: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 ror.** message i
2f00: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 s no longer need
2f10: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 ed..**.** The SQ
2f20: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
2f30: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 in the 2nd para
2f40: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
2f50: 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 3_exec()].** mus
2f60: 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 t remain unchang
2f70: 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ed while [sqlite
2f80: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 3_exec()] is run
2f90: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ning..**.** Requ
2fa0: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
2fb0: 32 31 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 2101] [H12102] [
2fc0: 48 31 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d H12104] [H12105]
2fd0: 20 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 [H12107] [H1211
2fe0: 30 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 0] [H12113] [H12
2ff0: 31 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 116].** [H12119]
3000: 20 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 [H12122] [H1212
3010: 35 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 5] [H12131] [H12
3020: 31 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 134] [H12137] [H
3030: 31 32 31 33 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 12138].*/.SQLITE
3040: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
3050: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 _exec(. sqlite3
3060: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
3070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3080: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
3090: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
30a0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 st char *sql,
30b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
30c0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 /* SQL t
30d0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
30e0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 /. int (*callba
30f0: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
3100: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f ar**,char**), /
3110: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * Callback funct
3120: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c ion */. void *,
3130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3150: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d /* 1st argum
3160: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 ent to callback
3170: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d */. char **errm
3180: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 sg
3190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
31a0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
31b0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
31c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
31d0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 Result Codes {H
31e0: 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 10210} <S10700>.
31f0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c ** KEYWORDS: SQL
3200: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f ITE_OK {error co
3210: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 de} {error codes
3220: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
3230: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 result code} {re
3240: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a sult codes}.**.*
3250: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 * Many SQLite fu
3260: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 nctions return a
3270: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 n integer result
3280: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 code from the s
3290: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 et shown.** here
32a0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 in order to ind
32b0: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f icates success o
32c0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a r failure..**.**
32d0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 New error codes
32e0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
32f0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
3300: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
3310: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c * See also: [SQL
3320: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c ITE_IOERR_READ |
3330: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
3340: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 codes].*/.#defi
3350: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 ne SQLITE_OK
3360: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 0 /* Su
3370: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 ccessful result
3380: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d */./* beginning-
3390: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a of-error-codes *
33a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
33b0: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 _ERROR 1
33c0: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f /* SQL error o
33d0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 r missing databa
33e0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 se */.#define SQ
33f0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 LITE_INTERNAL
3400: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 2 /* Interna
3410: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e l logic error in
3420: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 SQLite */.#defi
3430: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 ne SQLITE_PERM
3440: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 3 /* Ac
3450: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 cess permission
3460: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
3470: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 e SQLITE_ABORT
3480: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 4 /* Cal
3490: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 lback routine re
34a0: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 quested an abort
34b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
34c0: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 TE_BUSY
34d0: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 5 /* The datab
34e0: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b ase file is lock
34f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
3500: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 LITE_LOCKED
3510: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 6 /* A table
3520: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 in the database
3530: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 is locked */.#d
3540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d efine SQLITE_NOM
3550: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a EM 7 /*
3560: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c A malloc() fail
3570: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
3580: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 LITE_READONLY
3590: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 8 /* Attempt
35a0: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 to write a read
35b0: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f only database */
35c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
35d0: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 INTERRUPT 9
35e0: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 /* Operation te
35f0: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 rminated by sqli
3600: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a te3_interrupt()*
3610: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3620: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 _IOERR 10
3630: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f /* Some kind o
3640: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 f disk I/O error
3650: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 occurred */.#de
3660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 fine SQLITE_CORR
3670: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 UPT 11 /*
3680: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 The database dis
3690: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f k image is malfo
36a0: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rmed */.#define
36b0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 SQLITE_NOTFOUND
36c0: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 12 /* NOT U
36d0: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 SED. Table or re
36e0: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a cord not found *
36f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3700: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 _FULL 13
3710: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 /* Insertion f
3720: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 ailed because da
3730: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a tabase is full *
3740: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3750: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 _CANTOPEN 14
3760: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f /* Unable to o
3770: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
3780: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 file */.#define
3790: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c SQLITE_PROTOCOL
37a0: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 15 /* NOT
37b0: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c USED. Database l
37c0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 ock protocol err
37d0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
37e0: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 LITE_EMPTY
37f0: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 16 /* Databas
3800: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 e is empty */.#d
3810: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 efine SQLITE_SCH
3820: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a EMA 17 /*
3830: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 The database sc
3840: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a hema changed */.
3850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
3860: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 OOBIG 18
3870: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f /* String or BLO
3880: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c B exceeds size l
3890: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 imit */.#define
38a0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
38b0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 T 19 /* Abort
38c0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 due to constrai
38d0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a nt violation */.
38e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
38f0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 ISMATCH 20
3900: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 /* Data type mis
3910: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 match */.#define
3920: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 SQLITE_MISUSE
3930: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 21 /* Libr
3940: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 ary used incorre
3950: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ctly */.#define
3960: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 SQLITE_NOLFS
3970: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 22 /* Uses
3980: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 OS features not
3990: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 supported on hos
39a0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
39b0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 ITE_AUTH
39c0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 23 /* Authoriz
39d0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a ation denied */.
39e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
39f0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 ORMAT 24
3a00: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 /* Auxiliary dat
3a10: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 abase format err
3a20: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
3a30: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 LITE_RANGE
3a40: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 25 /* 2nd par
3a50: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3a60: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 3_bind out of ra
3a70: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nge */.#define S
3a80: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 QLITE_NOTADB
3a90: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 26 /* File o
3aa0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f pened that is no
3ab0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
3ac0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
3ad0: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 ITE_ROW
3ae0: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 100 /* sqlite3_
3af0: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 step() has anoth
3b00: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a er row ready */.
3b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
3b20: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 ONE 101
3b30: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
3b40: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 ) has finished e
3b50: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 xecuting */./* e
3b60: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 nd-of-error-code
3b70: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 s */../*.** CAPI
3b80: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 3REF: Extended R
3b90: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 esult Codes {H10
3ba0: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 220} <S10700>.**
3bb0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 KEYWORDS: {exte
3bc0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d nded error code}
3bd0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 {extended error
3be0: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f codes}.** KEYWO
3bf0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 RDS: {extended r
3c00: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 esult code} {ext
3c10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
3c20: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 es}.**.** In its
3c30: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
3c40: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 ration, SQLite A
3c50: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 PI routines retu
3c60: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 rn one of 26 int
3c70: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f eger.** [SQLITE_
3c80: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 OK | result code
3c90: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 s]. However, ex
3ca0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f perience has sho
3cb0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a wn that many of.
3cc0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 ** these result
3cd0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f codes are too co
3ce0: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 arse-grained. T
3cf0: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 hey do not provi
3d00: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e de as.** much in
3d10: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
3d20: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 problems as prog
3d30: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 rammers might li
3d40: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 ke. In an effor
3d50: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 t to.** address
3d60: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 this, newer vers
3d70: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 ions of SQLite (
3d80: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e version 3.3.8 an
3d90: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 d later) include
3da0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 .** support for
3db0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c additional resul
3dc0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f t codes that pro
3dd0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c vide more detail
3de0: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ed information.*
3df0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 * about errors.
3e00: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 The extended res
3e10: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e ult codes are en
3e20: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
3e30: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 d.** on a per da
3e40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3e50: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 n basis using th
3e60: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 e.** [sqlite3_ex
3e70: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
3e80: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a des()] API..**.*
3e90: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 * Some of the av
3ea0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 ailable extended
3eb0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
3ec0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a e listed here..*
3ed0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 * One may expect
3ee0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
3ef0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
3f00: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 odes will be exp
3f10: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 and.** over time
3f20: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
3f30: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 uses extended r
3f40: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 esult codes shou
3f50: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 ld expect.** to
3f60: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 see new result c
3f70: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 odes in future r
3f80: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
3f90: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c e..**.** The SQL
3fa0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f ITE_OK result co
3fb0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 de will never be
3fc0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 extended. It w
3fd0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 ill always.** be
3fe0: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a exactly zero..*
3ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4000: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 _IOERR_READ
4010: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4020: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 _IOERR | (1<<8))
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4040: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
4050: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
4060: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a IOERR | (2<<8)).
4070: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4080: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 OERR_WRITE
4090: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
40a0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OERR | (3<<8)).#
40b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
40c0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 ERR_FSYNC
40d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
40e0: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 ERR | (4<<8)).#d
40f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4100: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 RR_DIR_FSYNC
4110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4120: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 RR | (5<<8)).#de
4130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4140: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 R_TRUNCATE
4150: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4160: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 R | (6<<8)).#def
4170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4180: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 _FSTAT
4190: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
41a0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
41b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
41c0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 UNLOCK
41d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
41e0: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (8<<8)).#defin
41f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
4200: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 DLOCK
4210: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4220: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
4230: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
4240: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
4250: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4260: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (10<<8)).#define
4270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c SQLITE_IOERR_BL
4280: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 OCKED
4290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
42a0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (11<<8)).#define
42b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f SQLITE_IOERR_NO
42c0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 MEM
42d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
42e0: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (12<<8)).#define
42f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 SQLITE_IOERR_AC
4300: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 CESS
4310: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4320: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (13<<8)).#define
4330: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 SQLITE_IOERR_CH
4340: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 ECKRESERVEDLOCK
4350: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4360: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (14<<8)).#define
4370: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f SQLITE_IOERR_LO
4380: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
4390: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
43a0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (15<<8)).#define
43b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c SQLITE_IOERR_CL
43c0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 OSE
43d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
43e0: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (16<<8)).#define
43f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
4400: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 R_CLOSE
4410: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4420: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (17<<8)).#define
4430: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 SQLITE_LOCKED_S
4440: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
4450: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c (SQLITE_LOCKED |
4460: 20 28 31 3c 3c 38 29 20 29 0a 0a 2f 2a 0a 2a 2a (1<<8) )../*.**
4470: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
4480: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f For File Open O
4490: 70 65 72 61 74 69 6f 6e 73 20 7b 48 31 30 32 33 perations {H1023
44a0: 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 32 0} <H11120> <H12
44b0: 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 700>.**.** These
44c0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 bit values are
44d0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
44e0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 in the.** 3rd p
44f0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
4500: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
4510: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e ()] interface an
4520: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 d.** in the 4th
4530: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
4540: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 xOpen method of
4550: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
4560: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f _vfs] object..*/
4570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4580: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
4590: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
45a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
45b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
45c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
45d0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
45e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
45f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4600: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4620: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
4630: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
4640: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4650: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4670: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
4680: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
4690: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
46a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
46b0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
46c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
46d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
46e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
46f0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
4700: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
4710: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4730: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
4740: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
4750: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4770: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
4780: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
4790: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
47a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
47b0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
47c0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
47d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
47e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
47f0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
4800: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
4810: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4830: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
4840: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
4850: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4870: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
4880: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
4890: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
48b0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
48c0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
48d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
48e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
48f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4900: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
4910: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
4920: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4930: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4950: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
4960: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
4970: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4980: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
49a0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
49b0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
49c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
49d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
49e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
49f0: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 : Device Charact
4a00: 65 72 69 73 74 69 63 73 20 7b 48 31 30 32 34 30 eristics {H10240
4a10: 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a } <H11120>.**.**
4a20: 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70 61 The xDeviceCapa
4a30: 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 bilities method
4a40: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
4a50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f io_methods].** o
4a60: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e bject returns an
4a70: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
4a80: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 s a vector of th
4a90: 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 e these.** bit v
4aa0: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 alues expressing
4ab0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 I/O characteris
4ac0: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 tics of the mass
4ad0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 storage.** devi
4ae0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 ce that holds th
4af0: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 e file that the
4b00: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
4b10: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 ods].** refers t
4b20: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c o..**.** The SQL
4b30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
4b40: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
4b50: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 that all writes
4b60: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 of.** any size a
4b70: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
4b80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
4b90: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a MICnnn values.**
4ba0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 mean that write
4bb0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 s of blocks that
4bc0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 are nnn bytes i
4bd0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 n size and.** ar
4be0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
4bf0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 address which is
4c00: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 an integer mult
4c10: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 iple of.** nnn a
4c20: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
4c30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
4c40: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d E_APPEND value m
4c50: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 eans.** that whe
4c60: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 n data is append
4c70: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 ed to a file, th
4c80: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 e data is append
4c90: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e ed.** first then
4ca0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
4cb0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 file is extende
4cc0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 d, never the oth
4cd0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 er.** way around
4ce0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
4cf0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 CAP_SEQUENTIAL p
4d00: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
4d10: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f at.** informatio
4d20: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 n is written to
4d30: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 disk in the same
4d40: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a order as calls.
4d50: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a ** to xWrite()..
4d60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4d70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 E_IOCAP_ATOMIC
4d80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
4d90: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 01.#define SQLIT
4da0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
4db0: 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 2 0x000000
4dc0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 02.#define SQLIT
4dd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b E_IOCAP_ATOMIC1K
4de0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
4df0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 04.#define SQLIT
4e00: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b E_IOCAP_ATOMIC2K
4e10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
4e20: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 08.#define SQLIT
4e30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b E_IOCAP_ATOMIC4K
4e40: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
4e50: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
4e60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b E_IOCAP_ATOMIC8K
4e70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
4e80: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 20.#define SQLIT
4e90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 E_IOCAP_ATOMIC16
4ea0: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 K 0x000000
4eb0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 40.#define SQLIT
4ec0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 E_IOCAP_ATOMIC32
4ed0: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 K 0x000000
4ee0: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 80.#define SQLIT
4ef0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
4f00: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 K 0x000001
4f10: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
4f20: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
4f30: 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32 END 0x000002
4f40: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
4f50: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
4f60: 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34 AL 0x000004
4f70: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 00../*.** CAPI3R
4f80: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 EF: File Locking
4f90: 20 4c 65 76 65 6c 73 20 7b 48 31 30 32 35 30 7d Levels {H10250}
4fa0: 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 31 33 31 <H11120> <H1131
4fb0: 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 0>.**.** SQLite
4fc0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 uses one of thes
4fd0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
4fe0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
4ff0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 * argument to ca
5000: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 lls it makes to
5010: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 the xLock() and
5020: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 xUnlock() method
5030: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 s.** of an [sqli
5040: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
5050: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
5060: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e ne SQLITE_LOCK_N
5070: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 ONE 0.#
5080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
5090: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 CK_SHARED
50a0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
50b0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 E_LOCK_RESERVED
50c0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
50d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
50e0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 NG 3.#defi
50f0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 ne SQLITE_LOCK_E
5100: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a XCLUSIVE 4..
5110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
5120: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 Synchronization
5130: 54 79 70 65 20 46 6c 61 67 73 20 7b 48 31 30 32 Type Flags {H102
5140: 36 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 60} <H11120>.**.
5150: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 ** When SQLite i
5160: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 nvokes the xSync
5170: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a () method of an.
5180: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d ** [sqlite3_io_m
5190: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 ethods] object i
51a0: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 t uses a combina
51b0: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 tion of.** these
51c0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
51d0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
51e0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 gument..**.** Wh
51f0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 en the SQLITE_SY
5200: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 NC_DATAONLY flag
5210: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 is used, it mea
5220: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 ns that the.** s
5230: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e ync operation on
5240: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 ly needs to flus
5250: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 h data to mass s
5260: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a torage. Inode.*
5270: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 * information ne
5280: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 ed not be flushe
5290: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 d. If the lower
52a0: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 four bits of the
52b0: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 flag.** equal S
52c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
52d0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f L, that means to
52e0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e use normal fsyn
52f0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a c() semantics..*
5300: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 * If the lower f
5310: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 our bits equal S
5320: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c QLITE_SYNC_FULL,
5330: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 that means.** t
5340: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 o use Mac OS X s
5350: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e tyle fullsync in
5360: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 stead of fsync()
5370: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
5380: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
5390: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 0x00002.#
53a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
53b0: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 NC_FULL
53c0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 0x00003.#define
53d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
53e0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 AONLY 0x000
53f0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 10../*.** CAPI3R
5400: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 EF: OS Interface
5410: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c Open File Handl
5420: 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30 31 e {H11110} <S201
5430: 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 10>.**.** An [sq
5440: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
5450: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e ct represents an
5460: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 open file in th
5470: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 e .** [sqlite3_v
5480: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 fs | OS interfac
5490: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 e layer]. Indiv
54a0: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 idual OS interfa
54b0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ce.** implementa
54c0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 tions will.** wa
54d0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 nt to subclass t
54e0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 his object by ap
54f0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e pending addition
5500: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 al fields.** for
5510: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 their own use.
5520: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e The pMethods en
5530: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 try is a pointer
5540: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 to an.** [sqlit
5550: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
5560: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e bject that defin
5570: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 es methods for p
5580: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f erforming.** I/O
5590: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 operations on t
55a0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f he open file..*/
55b0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
55c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c sqlite3_file sql
55d0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 ite3_file;.struc
55e0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b t sqlite3_file {
55f0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 . const struct
5600: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
5610: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f ds *pMethods; /
5620: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e * Methods for an
5630: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b open file */.};
5640: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
5650: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 : OS Interface F
5660: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 ile Virtual Meth
5670: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 ods Object {H111
5680: 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 20} <S20110>.**.
5690: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 ** Every file op
56a0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c ened by the [sql
56b0: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 ite3_vfs] xOpen
56c0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 method populates
56d0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
56e0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 file] object (or
56f0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c , more commonly,
5700: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 a subclass of t
5710: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 he.** [sqlite3_f
5720: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 ile] object) wit
5730: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 h a pointer to a
5740: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
5750: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 is object..** Th
5760: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 is object define
5770: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 s the methods us
5780: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 ed to perform va
5790: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 rious operations
57a0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 .** against the
57b0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 open file repres
57c0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 ented by the [sq
57d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
57e0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ct..**.** If the
57f0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 73 65 xOpen method se
5800: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 ts the sqlite3_f
5810: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 ile.pMethods ele
5820: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f ment .** to a no
5830: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 n-NULL pointer,
5840: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
5850: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f _io_methods.xClo
5860: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 se method.** may
5870: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e be invoked even
5880: 20 69 66 20 74 68 65 20 78 4f 70 65 6e 20 72 65 if the xOpen re
5890: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 ported that it f
58a0: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f ailed. The.** o
58b0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 nly way to preve
58c0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c nt a call to xCl
58d0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 ose following a
58e0: 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20 failed xOpen.**
58f0: 69 73 20 66 6f 72 20 74 68 65 20 78 4f 70 65 6e is for the xOpen
5900: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 to set the sqli
5910: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
5920: 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c s element to NUL
5930: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 L..**.** The fla
5940: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
5950: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 Sync may be one
5960: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f of [SQLITE_SYNC_
5970: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 NORMAL] or.** [S
5980: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d QLITE_SYNC_FULL]
5990: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f . The first cho
59a0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 ice is the norma
59b0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 l fsync()..** Th
59c0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 e second choice
59d0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 is a Mac OS X st
59e0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 yle fullsync. T
59f0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f he [SQLITE_SYNC_
5a00: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 DATAONLY].** fla
5a10: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e g may be ORed in
5a20: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
5a30: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 t only the data
5a40: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 of the file.** a
5a50: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 nd not its inode
5a60: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e needs to be syn
5a70: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ced..**.** The i
5a80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f nteger values to
5a90: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
5aa0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f lock() are one o
5ab0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 f.** <ul>.** <li
5ac0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e > [SQLITE_LOCK_N
5ad0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ONE],.** <li> [S
5ae0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
5af0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
5b00: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
5b10: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
5b20: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
5b30: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
5b40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
5b50: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a SIVE]..** </ul>.
5b60: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 ** xLock() incre
5b70: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 ases the lock. x
5b80: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 Unlock() decreas
5b90: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 es the lock..**
5ba0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 The xCheckReserv
5bb0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 edLock() method
5bc0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 checks whether a
5bd0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
5be0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 ection,.** eithe
5bf0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 r in this proces
5c00: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 s or in some oth
5c10: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 er process, is h
5c20: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 olding a RESERVE
5c30: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f D,.** PENDING, o
5c40: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b r EXCLUSIVE lock
5c50: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 on the file. I
5c60: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a t returns true.*
5c70: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b * if such a lock
5c80: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 exists and fals
5c90: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a e otherwise..**.
5ca0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** The xFileCont
5cb0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 rol() method is
5cc0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 a generic interf
5cd0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 ace that allows
5ce0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d custom.** VFS im
5cf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f plementations to
5d00: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f directly contro
5d10: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 l an open file u
5d20: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
5d30: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
5d40: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 l()] interface.
5d50: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 The second "op"
5d60: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a argument is an.
5d70: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 ** integer opcod
5d80: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 e. The third ar
5d90: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 gument is a gene
5da0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 ric pointer inte
5db0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 nded to.** point
5dc0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 to a structure
5dd0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e that may contain
5de0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 arguments or sp
5df0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a ace in which to.
5e00: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 ** write return
5e10: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 values. Potenti
5e20: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c al uses for xFil
5e30: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 eControl() might
5e40: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 be.** functions
5e50: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b to enable block
5e60: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 ing locks with t
5e70: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e imeouts, to chan
5e80: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e ge the.** lockin
5e90: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 g strategy (for
5ea0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 example to use d
5eb0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 ot-file locks),
5ec0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 to inquire.** ab
5ed0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f out the status o
5ee0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 f a lock, or to
5ef0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b break stale lock
5f00: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a s. The SQLite.*
5f10: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 * core reserves
5f20: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 all opcodes less
5f30: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 than 100 for it
5f40: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 s own use..** A
5f50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f [SQLITE_FCNTL_LO
5f60: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f CKSTATE | list o
5f70: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 f opcodes] less
5f80: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 than 100 is avai
5f90: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 lable..** Applic
5fa0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 ations that defi
5fb0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c ne a custom xFil
5fc0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
5fd0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 should use opcod
5fe0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 es.** greater th
5ff0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 an 100 to avoid
6000: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a conflicts..**.**
6010: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 The xSectorSize
6020: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e () method return
6030: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a s the sector siz
6040: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 e of the.** devi
6050: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 ce that underlie
6060: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 s the file. The
6070: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 sector size is
6080: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 the.** minimum w
6090: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 rite that can be
60a0: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f performed witho
60b0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a ut disturbing.**
60c0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 other bytes in
60d0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 the file. The x
60e0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
60f0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f stics().** metho
6100: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 d returns a bit
6110: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e vector describin
6120: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 g behaviors of t
6130: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 he.** underlying
6140: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c device:.**.** <
6150: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
6160: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6170: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
6180: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
6190: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 2].** <li> [SQLI
61a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
61b0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
61c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 TE_IOCAP_ATOMIC2
61d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
61e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
61f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
6200: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 TE_IOCAP_ATOMIC8
6210: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
6220: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
6230: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 6K].** <li> [SQL
6240: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6250: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 32K].** <li> [SQ
6260: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6270: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C64K].** <li> [S
6280: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
6290: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e _APPEND].** <li>
62a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
62b0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f EQUENTIAL].** </
62c0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 ul>.**.** The SQ
62d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
62e0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
62f0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
6300: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
6310: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
6320: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6330: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
6340: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
6350: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
6360: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
6370: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
6380: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
6390: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
63a0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
63b0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
63c0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
63d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
63e0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
63f0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
6400: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
6410: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
6420: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
6430: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
6440: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
6450: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
6460: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
6470: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
6480: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
6490: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
64a0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
64b0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
64c0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
64d0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
64e0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
64f0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
6500: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 .**.** If xRead(
6510: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 ) returns SQLITE
6520: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 _IOERR_SHORT_REA
6530: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 D it must also f
6540: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e ill.** in the un
6550: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 read portions of
6560: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 the buffer with
6570: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 zeros. A VFS t
6580: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 hat.** fails to
6590: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
65a0: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d reads might seem
65b0: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 to work. Howev
65c0: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 er,.** failure t
65d0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
65e0: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 t reads will eve
65f0: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a ntually lead to.
6600: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 ** database corr
6610: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 uption..*/.typed
6620: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
6630: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 3_io_methods sql
6640: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b ite3_io_methods;
6650: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
6660: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 io_methods {. i
6670: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
6680: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c nt (*xClose)(sql
6690: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
66a0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 nt (*xRead)(sqli
66b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a te3_file*, void*
66c0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
66d0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
66e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 ;. int (*xWrite
66f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
6700: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
6710: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f t iAmt, sqlite3_
6720: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 int64 iOfst);.
6730: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 int (*xTruncate)
6740: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
6750: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 sqlite3_int64 si
6760: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 ze);. int (*xSy
6770: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 nc)(sqlite3_file
6780: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 *, int flags);.
6790: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 int (*xFileSize
67a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
67b0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
67c0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a pSize);. int (*
67d0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 xLock)(sqlite3_f
67e0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
67f0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c t (*xUnlock)(sql
6800: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
6810: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b ;. int (*xCheck
6820: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 ReservedLock)(sq
6830: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
6840: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e *pResOut);. in
6850: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c t (*xFileControl
6860: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
6870: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 int op, void *p
6880: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Arg);. int (*xS
6890: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 ectorSize)(sqlit
68a0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
68b0: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 (*xDeviceCharac
68c0: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 teristics)(sqlit
68d0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 e3_file*);. /*
68e0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f Additional metho
68f0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ds may be added
6900: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
6910: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 es */.};../*.**
6920: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 CAPI3REF: Standa
6930: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 rd File Control
6940: 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d Opcodes {H11310}
6950: 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S30800>.**.**
6960: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
6970: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f nstants are opco
6980: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c des for the xFil
6990: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
69a0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
69b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
69c0: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 bject and for th
69d0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f e [sqlite3_file_
69e0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e control()].** in
69f0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 terface..**.** T
6a00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
6a10: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f _LOCKSTATE] opco
6a20: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 de is used for d
6a30: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a ebugging. This.
6a40: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 ** opcode causes
6a50: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
6a60: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 l method to writ
6a70: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 e the current st
6a80: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f ate of.** the lo
6a90: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 ck (one of [SQLI
6aa0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b TE_LOCK_NONE], [
6ab0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
6ac0: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ED],.** [SQLITE_
6ad0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 LOCK_RESERVED],
6ae0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
6af0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 DING], or [SQLIT
6b00: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
6b10: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e ]).** into an in
6b20: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 teger that the p
6b30: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 Arg argument poi
6b40: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 nts to. This cap
6b50: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 ability.** is us
6b60: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
6b70: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 g and only needs
6b80: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
6b90: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 when SQLITE_TES
6ba0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e T.** is defined.
6bb0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
6bc0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
6bd0: 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 TE 1.#def
6be0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c ine SQLITE_GET_L
6bf0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
6c00: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
6c10: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_SET_LOCKPROXY
6c20: 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 FILE 3.#def
6c30: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f ine SQLITE_LAST_
6c40: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 ERRNO
6c50: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 4../*.** CAPI3
6c60: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c REF: Mutex Handl
6c70: 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 e {H17110} <S201
6c80: 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 30>.**.** The mu
6c90: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 tex module withi
6ca0: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 n SQLite defines
6cb0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
6cc0: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 to be an.** abs
6cd0: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 tract type for a
6ce0: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 mutex object.
6cf0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
6d00: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 never looks.** a
6d10: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 t the internal r
6d20: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 epresentation of
6d30: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 an [sqlite3_mut
6d40: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a ex]. It only.**
6d50: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e deals with poin
6d60: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c ters to the [sql
6d70: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 ite3_mutex] obje
6d80: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 ct..**.** Mutexe
6d90: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
6da0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
6db0: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a ex_alloc()]..*/.
6dc0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
6dd0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c qlite3_mutex sql
6de0: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a ite3_mutex;../*.
6df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
6e00: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 Interface Object
6e10: 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 {H11140} <S2010
6e20: 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 0>.**.** An inst
6e30: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
6e40: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 te3_vfs object d
6e50: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
6e60: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 face between.**
6e70: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 the SQLite core
6e80: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 and the underlyi
6e90: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
6ea0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a tem. The "vfs".
6eb0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f ** in the name o
6ec0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 f the object sta
6ed0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c nds for "virtual
6ee0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a file system"..*
6ef0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f *.** The value o
6f00: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 f the iVersion f
6f10: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c ield is initiall
6f20: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c y 1 but may be l
6f30: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 arger in.** futu
6f40: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
6f50: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e QLite. Addition
6f60: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 al fields may be
6f70: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 appended to thi
6f80: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e s.** object when
6f90: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 the iVersion va
6fa0: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 lue is increased
6fb0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 . Note that the
6fc0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 structure.** of
6fd0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
6fe0: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 object changes
6ff0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 in the transacti
7000: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 on between.** SQ
7010: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
7020: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 .9 and 3.6.0 and
7030: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f yet the iVersio
7040: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a n field was not.
7050: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a ** modified..**.
7060: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 ** The szOsFile
7070: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a field is the siz
7080: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 e of the subclas
7090: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c sed [sqlite3_fil
70a0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 e].** structure
70b0: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 used by this VFS
70c0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 . mxPathname is
70d0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e the maximum len
70e0: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 gth of.** a path
70f0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 name in this VFS
7100: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
7110: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f ed sqlite3_vfs o
7120: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 bjects are kept
7130: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 on a linked list
7140: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 formed by.** th
7150: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
7160: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
7170: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a fs_register()].*
7180: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 * and [sqlite3_v
7190: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d fs_unregister()]
71a0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 interfaces mana
71b0: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 ge this list.**
71c0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 in a thread-safe
71d0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 way. The [sqli
71e0: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 te3_vfs_find()]
71f0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 interface.** sea
7200: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 rches the list.
7210: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 Neither the app
7220: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f lication code no
7230: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 r the VFS.** imp
7240: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
7250: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 ld use the pNext
7260: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
7270: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 The pNext field
7280: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c is the only fiel
7290: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 d in the sqlite3
72a0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 _vfs.** structur
72b0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 e that SQLite wi
72c0: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 ll ever modify.
72d0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
72e0: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d y access.** or m
72f0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 odify this field
7300: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 while holding a
7310: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 particular stat
7320: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 ic mutex..** The
7330: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
7340: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 uld never modify
7350: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e anything within
7360: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
7370: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 .** object once
7380: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 the object has b
7390: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a een registered..
73a0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 **.** The zName
73b0: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 field holds the
73c0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 name of the VFS
73d0: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d module. The nam
73e0: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 e must.** be uni
73f0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 que across all V
7400: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a FS modules..**.*
7410: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 * SQLite will gu
7420: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 arantee that the
7430: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
7440: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a eter to xOpen.**
7450: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c is either a NUL
7460: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 L pointer or str
7470: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ing obtained.**
7480: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 from xFullPathna
7490: 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 me(). SQLite fu
74a0: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 rther guarantees
74b0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 that.** the str
74c0: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 ing will be vali
74d0: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 d and unchanged
74e0: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 until xClose() i
74f0: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 s.** called. Bec
7500: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 ause of the prev
7510: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a ious sentence,.*
7520: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 * the [sqlite3_f
7530: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 ile] can safely
7540: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 store a pointer
7550: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 to the.** filena
7560: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 me if it needs t
7570: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 o remember the f
7580: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 ilename for some
7590: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 reason..** If t
75a0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 he zFilename par
75b0: 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 ameter is xOpen
75c0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
75d0: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 r then xOpen.**
75e0: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 must invent its
75f0: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 own temporary na
7600: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e me for the file.
7610: 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a Whenever the .
7620: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 ** xFilename par
7630: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 ameter is NULL i
7640: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 t will also be t
7650: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
7660: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 .** flags parame
7670: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 ter will include
7680: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
7690: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a LETEONCLOSE]..**
76a0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
76b0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 gument to xOpen(
76c0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 ) includes all b
76d0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 its set in.** th
76e0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
76f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
7700: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 n_v2()]. Or if
7710: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
7720: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
7730: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 open16()] is use
7740: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e d, then flags in
7750: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a cludes at least.
7760: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
7770: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
7780: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
7790: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 ]. .** If xOpen(
77a0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 ) opens a file r
77b0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 ead-only then it
77c0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 sets *pOutFlags
77d0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b to.** include [
77e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
77f0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 ONLY]. Other bi
7800: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 ts in *pOutFlags
7810: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a may be set..**.
7820: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 ** SQLite will a
7830: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
7840: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
7850: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 gs to the xOpen(
7860: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e ).** call, depen
7870: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 ding on the obje
7880: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a ct being opened:
7890: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
78a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
78b0: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c N_MAIN_DB].** <l
78c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
78d0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a _MAIN_JOURNAL].*
78e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
78f0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a OPEN_TEMP_DB].**
7900: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
7910: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c PEN_TEMP_JOURNAL
7920: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
7930: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e TE_OPEN_TRANSIEN
7940: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b T_DB].** <li> [
7950: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a SQLITE_OPEN_SUBJ
7960: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
7970: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
7980: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a STER_JOURNAL].**
7990: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
79a0: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d file I/O implem
79b0: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 entation can use
79c0: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 the object type
79d0: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 flags to.** cha
79e0: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 nge the way it d
79f0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e eals with files.
7a00: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 For example, a
7a10: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a n application.**
7a20: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 that does not c
7a30: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 are about crash
7a40: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c recovery or roll
7a50: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a back might make.
7a60: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 ** the open of a
7a70: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 journal file a
7a80: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 no-op. Writes t
7a90: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 o this journal w
7aa0: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 ould.** also be
7ab0: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 no-ops, and any
7ac0: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 attempt to read
7ad0: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c the journal woul
7ae0: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 d return.** SQLI
7af0: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 TE_IOERR. Or th
7b00: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
7b10: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 might recognize
7b20: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 that a database
7b30: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 .** file will be
7b40: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 doing page-alig
7b50: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 ned sector reads
7b60: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 and writes in a
7b70: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 random.** order
7b80: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 and set up its
7b90: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 I/O subsystem ac
7ba0: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a cordingly..**.**
7bb0: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c SQLite might al
7bc0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
7bd0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
7be0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d s to the xOpen m
7bf0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ethod:.**.** <ul
7c00: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
7c10: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
7c20: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 LOSE].** <li> [S
7c30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
7c40: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a SIVE].** </ul>.*
7c50: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
7c60: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
7c70: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 OSE] flag means
7c80: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
7c90: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 be.** deleted wh
7ca0: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e en it is closed.
7cb0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 The [SQLITE_OP
7cc0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
7cd0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 ].** will be set
7ce0: 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 for TEMP datab
7cf0: 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 ases, journals a
7d00: 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 nd for subjourna
7d10: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 ls..**.** The [S
7d20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
7d30: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c SIVE] flag is al
7d40: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e ways used in con
7d50: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 junction.** with
7d60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
7d70: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 N_CREATE] flag,
7d80: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 which are both d
7d90: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f irectly.** analo
7da0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 gous to the O_EX
7db0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 CL and O_CREAT f
7dc0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 lags of the POSI
7dd0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e X open().** API.
7de0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 The SQLITE_OPE
7df0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 N_EXCLUSIVE flag
7e00: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 , when paired wi
7e10: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 th the .** SQLIT
7e20: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 E_OPEN_CREATE, i
7e30: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 s used to indica
7e40: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f te that file sho
7e50: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 uld always.** be
7e60: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 created, and th
7e70: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f at it is an erro
7e80: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 r if it already
7e90: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 exists..** It is
7ea0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 <i>not</i> used
7eb0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 to indicate the
7ec0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 file should be
7ed0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 opened .** for e
7ee0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e xclusive access.
7ef0: 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20 .**.** At least
7f00: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f szOsFile bytes o
7f10: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c f memory are all
7f20: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 ocated by SQLite
7f30: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 .** to hold the
7f40: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
7f50: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 structure passed
7f60: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a as the third.**
7f70: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 argument to xOp
7f80: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d en. The xOpen m
7f90: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 ethod does not h
7fa0: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 ave to.** alloca
7fb0: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 te the structure
7fc0: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 ; it should just
7fd0: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f fill it in. No
7fe0: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 te that.** the x
7ff0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 Open method must
8000: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 set the sqlite3
8010: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 _file.pMethods t
8020: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 o either.** a va
8030: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f lid [sqlite3_io_
8040: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
8050: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 or to NULL. xOp
8060: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 en must do.** th
8070: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f is even if the o
8080: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 pen fails. SQLi
8090: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 te expects that
80a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
80b0: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 .pMethods.** ele
80c0: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c ment will be val
80d0: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 id after xOpen r
80e0: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 eturns regardles
80f0: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 s of the success
8100: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f .** or failure o
8110: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c f the xOpen call
8120: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
8130: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 s argument to xA
8140: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b ccess() may be [
8150: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
8160: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 ISTS].** to test
8170: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e for the existen
8180: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 ce of a file, or
8190: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
81a0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a READWRITE] to.**
81b0: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
81c0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
81d0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f and writable, o
81e0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
81f0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 _READ].** to tes
8200: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 t whether a file
8210: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 is at least rea
8220: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c dable. The fil
8230: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 e can be a.** di
8240: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 rectory..**.** S
8250: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 QLite will alway
8260: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 s allocate at le
8270: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 ast mxPathname+1
8280: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a bytes for the.*
8290: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 * output buffer
82a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 xFullPathname.
82b0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f The exact size o
82c0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
82d0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 fer.** is also p
82e0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d assed as a param
82f0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 eter to both me
8300: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
8310: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
8320: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
8330: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 gh, [SQLITE_CANT
8340: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 OPEN] should be
8350: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 returned. Since
8360: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c this is.** handl
8370: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 ed as a fatal er
8380: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 ror by SQLite, v
8390: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f fs implementatio
83a0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 ns should endeav
83b0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 or.** to prevent
83c0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 this by setting
83d0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 mxPathname to a
83e0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 sufficiently la
83f0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a rge value..**.**
8400: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
8410: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e (), xSleep(), an
8420: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 d xCurrentTime()
8430: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 interfaces.** a
8440: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 re not strictly
8450: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 a part of the fi
8460: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 lesystem, but th
8470: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 ey are.** includ
8480: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 ed in the VFS st
8490: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 ructure for comp
84a0: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 leteness..** The
84b0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 xRandomness() f
84c0: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 unction attempts
84d0: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 to return nByte
84e0: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f s bytes.** of go
84f0: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f od-quality rando
8500: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e mness into zOut.
8510: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c The return val
8520: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 ue is.** the act
8530: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 ual number of by
8540: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 tes of randomnes
8550: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 s obtained..** T
8560: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 he xSleep() meth
8570: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 od causes the ca
8580: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 lling thread to
8590: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 sleep for at.**
85a0: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 least the number
85b0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 of microseconds
85c0: 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 given. The xCu
85d0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d rrentTime().** m
85e0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
85f0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 Julian Day Numbe
8600: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e r for the curren
8610: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 2e t date and time.
8620: 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 .**.*/.typedef s
8630: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
8640: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 s sqlite3_vfs;.s
8650: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
8660: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 s {. int iVersi
8670: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f on; /
8680: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 * Structure vers
8690: 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 ion number */.
86a0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 int szOsFile;
86b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 /* Size
86c0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 of subclassed s
86d0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 qlite3_file */.
86e0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b int mxPathname;
86f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
8700: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 imum file pathna
8710: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 me length */. s
8720: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 qlite3_vfs *pNex
8730: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 t; /* Next
8740: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a registered VFS *
8750: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
8760: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 zName; /*
8770: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 Name of this vir
8780: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
8790: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
87a0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f Data; /
87b0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 * Pointer to app
87c0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 lication-specifi
87d0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 c data */. int
87e0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 (*xOpen)(sqlite3
87f0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
8800: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
8810: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 3_file*,.
8820: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 int flag
8830: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 s, int *pOutFlag
8840: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c s);. int (*xDel
8850: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ete)(sqlite3_vfs
8860: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
8870: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 Name, int syncDi
8880: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 r);. int (*xAcc
8890: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
88a0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
88b0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c Name, int flags,
88c0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
88d0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 int (*xFullPat
88e0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 hname)(sqlite3_v
88f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
8900: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 *zName, int nOut
8910: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
8920: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e void *(*xDlOpen
8930: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8940: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
8950: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 ename);. void (
8960: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 *xDlError)(sqlit
8970: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
8980: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 te, char *zErrMs
8990: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 g);. void (*(*x
89a0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 DlSym)(sqlite3_v
89b0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 fs*,void*, const
89c0: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 char *zSymbol))
89d0: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 (void);. void (
89e0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 *xDlClose)(sqlit
89f0: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b e3_vfs*, void*);
8a00: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d . int (*xRandom
8a10: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 ness)(sqlite3_vf
8a20: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
8a30: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e har *zOut);. in
8a40: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 t (*xSleep)(sqli
8a50: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 te3_vfs*, int mi
8a60: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 croseconds);. i
8a70: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
8a80: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
8a90: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 double*);. int
8aa0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 (*xGetLastError
8ab0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8ac0: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 int, char *);.
8ad0: 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 /* New fields ma
8ae0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e y be appended in
8af0: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 figure versions
8b00: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a . The iVersion.
8b10: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 ** value will
8b20: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 increment whenev
8b30: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e er this happens.
8b40: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
8b50: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f PI3REF: Flags fo
8b60: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 r the xAccess VF
8b70: 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30 S method {H11190
8b80: 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a } <H11140>.**.**
8b90: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
8ba0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 onstants can be
8bb0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 used as the thir
8bc0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
8bd0: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 * the xAccess me
8be0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 thod of an [sqli
8bf0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
8c00: 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 {END} They det
8c10: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b ermine.** what k
8c20: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f ind of permissio
8c30: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d ns the xAccess m
8c40: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 ethod is looking
8c50: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 for..** With SQ
8c60: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
8c70: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 TS, the xAccess
8c80: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 method.** simply
8c90: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
8ca0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e the file exists.
8cb0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
8cc0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
8cd0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 , the xAccess me
8ce0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 thod.** checks w
8cf0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 hether the file
8d00: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 is both readable
8d10: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a and writable..*
8d20: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 * With SQLITE_AC
8d30: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 CESS_READ, the x
8d40: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a Access method.**
8d50: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
8d60: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 the file is read
8d70: 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 able..*/.#define
8d80: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 SQLITE_ACCESS_E
8d90: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 XISTS 0.#defi
8da0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
8db0: 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 _READWRITE 1.#de
8dc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
8dd0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a SS_READ 2..
8de0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
8df0: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 Initialize The S
8e00: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 QLite Library {H
8e10: 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c 10130} <S20000><
8e20: 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30100>.**.** Th
8e30: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
8e40: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 lize() routine i
8e50: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a nitializes the.*
8e60: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 * SQLite library
8e70: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 . The sqlite3_s
8e80: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e hutdown() routin
8e90: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 e.** deallocates
8ea0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 any resources t
8eb0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 hat were allocat
8ec0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
8ed0: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 itialize()..** T
8ee0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
8ef0: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 e designed to ai
8f00: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 d in process ini
8f10: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a tialization and.
8f20: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 ** shutdown on e
8f30: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e mbedded systems.
8f40: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 Workstation ap
8f50: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 plications using
8f60: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 .** SQLite norma
8f70: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 lly do not need
8f80: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 to invoke either
8f90: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
8fa0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c es..**.** A call
8fb0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
8fc0: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 ialize() is an "
8fd0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
8fe0: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 if it is.** the
8ff0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
9000: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9010: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e is invoked durin
9020: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f g the lifetime o
9030: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 f.** the process
9040: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 , or if it is th
9050: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
9060: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
9070: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
9080: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c following a call
9090: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
90a0: 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e down(). Only an
90b0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a effective call.
90c0: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e ** of sqlite3_in
90d0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 itialize() does
90e0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 any initializati
90f0: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 on. All other c
9100: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d alls.** are harm
9110: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a less no-ops..**.
9120: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c ** A call to sql
9130: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
9140: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
9150: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 " call if it is
9160: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c the first.** cal
9170: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
9180: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 tdown() since th
9190: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 e last sqlite3_i
91a0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 4f 6e nitialize(). On
91b0: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 ly.** an effecti
91c0: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ve call to sqlit
91d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f e3_shutdown() do
91e0: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c es any deinitial
91f0: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 ization..** All
9200: 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c other valid call
9210: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 s to sqlite3_shu
9220: 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d tdown() are harm
9230: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a less no-ops..**.
9240: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 ** The sqlite3_i
9250: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 nitialize() inte
9260: 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 rface is threads
9270: 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 afe, but sqlite3
9280: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 _shutdown().** i
9290: 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 s not. The sqli
92a0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 te3_shutdown() i
92b0: 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e nterface must on
92c0: 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f ly be called fro
92d0: 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 m a.** single th
92e0: 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 read. All open
92f0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
9300: 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 tions] must be c
9310: 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a losed and all.**
9320: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 other SQLite re
9330: 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 sources must be
9340: 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f deallocated prio
9350: 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a r to invoking.**
9360: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
9370: 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 n()..**.** Among
9380: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 other things, s
9390: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
93a0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a e() will invoke.
93b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
93c0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 it(). Similarly
93d0: 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f , sqlite3_shutdo
93e0: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 wn().** will inv
93f0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 oke sqlite3_os_e
9400: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nd()..**.** The
9410: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9420: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 ze() routine ret
9430: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
9440: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 on success..**
9450: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 If for some reas
9460: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 on, sqlite3_init
9470: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 ialize() is unab
9480: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 le to initialize
9490: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 .** the library
94a0: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 (perhaps it is u
94b0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
94c0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 e a needed resou
94d0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 rce such.** as a
94e0: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 mutex) it retur
94f0: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 ns an [error cod
9500: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 e] other than [S
9510: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
9520: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
9530: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e tialize() routin
9540: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 e is called inte
9550: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f rnally by many o
9560: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ther.** SQLite i
9570: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 nterfaces so tha
9580: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e t an application
9590: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f usually does no
95a0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 t need to.** inv
95b0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
95c0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
95d0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c y. For example,
95e0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
95f0: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 ].** calls sqlit
9600: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9610: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 so the SQLite li
9620: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 brary will be au
9630: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 tomatically.** i
9640: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 nitialized when
9650: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
9660: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 is called if it
9670: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 has not be init
9680: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 ialized.** alrea
9690: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 dy. However, if
96a0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
96b0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 led with the [SQ
96c0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
96d0: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 IT].** compile-t
96e0: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e ime option, then
96f0: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 the automatic c
9700: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
9710: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 initialize().**
9720: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 are omitted and
9730: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
9740: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 must call sqlite
9750: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 3_initialize() d
9760: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 irectly.** prior
9770: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 to using any ot
9780: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
9790: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d face. For maxim
97a0: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a um portability,.
97b0: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 ** it is recomme
97c0: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 nded that applic
97d0: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e ations always in
97e0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 voke sqlite3_ini
97f0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 tialize().** dir
9800: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 ectly prior to u
9810: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 sing any other S
9820: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
9830: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 Future release
9840: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d s.** of SQLite m
9850: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e ay require this.
9860: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
9870: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 , the behavior e
9880: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e xhibited.** when
9890: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
98a0: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 led with [SQLITE
98b0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 _OMIT_AUTOINIT]
98c0: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 might become the
98d0: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 .** default beha
98e0: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 vior in some fut
98f0: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 ure release of S
9900: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 QLite..**.** The
9910: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
9920: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 () routine does
9930: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d operating-system
9940: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 specific.** ini
9950: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 tialization of t
9960: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
9970: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f y. The sqlite3_
9980: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 os_end().** rout
9990: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 ine undoes the e
99a0: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 ffect of sqlite3
99b0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 _os_init(). Typ
99c0: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 ical tasks.** pe
99d0: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 rformed by these
99e0: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 routines includ
99f0: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 e allocation or
9a00: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 deallocation.**
9a10: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 of static resour
9a20: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 ces, initializat
9a30: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 ion of global va
9a40: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 riables,.** sett
9a50: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 ing up a default
9a60: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d [sqlite3_vfs] m
9a70: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e odule, or settin
9a80: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c g up.** a defaul
9a90: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 t configuration
9aa0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
9ab0: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 onfig()]..**.**
9ac0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
9ad0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 should never inv
9ae0: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 oke either sqlit
9af0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
9b00: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e or sqlite3_os_en
9b10: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 d() directly. T
9b20: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
9b30: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b hould only invok
9b40: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 e.** sqlite3_ini
9b50: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 tialize() and sq
9b60: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
9b70: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f . The sqlite3_o
9b80: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 s_init().** inte
9b90: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 rface is called
9ba0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
9bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9bc0: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c ize() and.** sql
9bd0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 ite3_os_end() is
9be0: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 called by sqlit
9bf0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
9c00: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 Appropriate.** i
9c10: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 mplementations f
9c20: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e or sqlite3_os_in
9c30: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
9c40: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 _os_end().** are
9c50: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
9c60: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f te when it is co
9c70: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c mpiled for Unix,
9c80: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f Windows, or OS/
9c90: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 2..** When [cust
9ca0: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c om builds | buil
9cb0: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 t for other plat
9cc0: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 forms].** (using
9cd0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f the [SQLITE_OS_
9ce0: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 OTHER=1] compile
9cf0: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 -time.** option)
9d00: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
9d10: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 must supply a s
9d20: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e uitable implemen
9d30: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 tation for.** sq
9d40: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
9d50: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 and sqlite3_os_e
9d60: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 nd(). An applic
9d70: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a ation-supplied.*
9d80: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
9d90: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 of sqlite3_os_i
9da0: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 nit() or sqlite3
9db0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 _os_end().** mus
9dc0: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 t return [SQLITE
9dd0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 _OK] on success
9de0: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b and some other [
9df0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e error code] upon
9e00: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a .** failure..*/.
9e10: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
9e20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9e30: 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f e(void);.SQLITE_
9e40: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
9e50: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a shutdown(void);.
9e60: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
9e70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 qlite3_os_init(v
9e80: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
9e90: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f int sqlite3_os_
9ea0: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a end(void);../*.*
9eb0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
9ec0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 iguring The SQLi
9ed0: 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 34 31 te Library {H141
9ee0: 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 00} <S20000><S30
9ef0: 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 200>.** EXPERIME
9f00: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 NTAL.**.** The s
9f10: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
9f20: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
9f30: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c d to make global
9f40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
9f50: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c * changes to SQL
9f60: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ite in order to
9f70: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 tune SQLite to t
9f80: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 he specific need
9f90: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c s of.** the appl
9fa0: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 ication. The de
9fb0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
9fc0: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 ion is recommend
9fd0: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 ed for most.** a
9fe0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 pplications and
9ff0: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 so this routine
a000: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e is usually not n
a010: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 ecessary. It is
a020: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 .** provided to
a030: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 support rare app
a040: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 lications with u
a050: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a nusual needs..**
a060: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
a070: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
a080: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 ce is not thread
a090: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 safe. The appli
a0a0: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 cation.** must i
a0b0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 nsure that no ot
a0c0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
a0d0: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 faces are invoke
a0e0: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 d by other.** th
a0f0: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 reads while sqli
a100: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
a110: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 running. Furthe
a120: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 rmore, sqlite3_c
a130: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f onfig().** may o
a140: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 nly be invoked p
a150: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 rior to library
a160: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 initialization u
a170: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
a180: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f _initialize()] o
a190: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e r after shutdown
a1a0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 by [sqlite3_shu
a1b0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 tdown()]..** Not
a1c0: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 e, however, that
a1d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
a1e0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 ) can be called
a1f0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a as part of the.*
a200: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
a210: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 of an applicati
a220: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 on-defined [sqli
a230: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a te3_os_init()]..
a240: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
a250: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
a260: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
a270: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 an integer.** [S
a280: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
a290: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 GLETHREAD | conf
a2a0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
a2b0: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 ] that determine
a2c0: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 s.** what proper
a2d0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 ty of SQLite is
a2e0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 to be configured
a2f0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 . Subsequent ar
a300: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 guments.** vary
a310: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
a320: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
a330: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 SINGLETHREAD | c
a340: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
a350: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ion].** in the f
a360: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
a370: 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 *.** When a conf
a380: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
a390: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 is set, sqlite3
a3a0: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e _config() return
a3b0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a s [SQLITE_OK]..*
a3c0: 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 * If the option
a3d0: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 is unknown or SQ
a3e0: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
a3f0: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e o set the option
a400: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f .** then this ro
a410: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
a420: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
a430: 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 code]..**.** Req
a440: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
a450: 31 34 31 30 33 5d 20 5b 48 31 34 31 30 36 5d 20 14103] [H14106]
a460: 5b 48 31 34 31 32 30 5d 20 5b 48 31 34 31 32 33 [H14120] [H14123
a470: 5d 20 5b 48 31 34 31 32 36 5d 20 5b 48 31 34 31 ] [H14126] [H141
a480: 32 39 5d 20 5b 48 31 34 31 33 32 5d 20 5b 48 31 29] [H14132] [H1
a490: 34 31 33 35 5d 0a 2a 2a 20 5b 48 31 34 31 33 38 4135].** [H14138
a4a0: 5d 20 5b 48 31 34 31 34 31 5d 20 5b 48 31 34 31 ] [H14141] [H141
a4b0: 34 34 5d 20 5b 48 31 34 31 34 37 5d 20 5b 48 31 44] [H14147] [H1
a4c0: 34 31 35 30 5d 20 5b 48 31 34 31 35 33 5d 20 5b 4150] [H14153] [
a4d0: 48 31 34 31 35 36 5d 20 5b 48 31 34 31 35 39 5d H14156] [H14159]
a4e0: 0a 2a 2a 20 5b 48 31 34 31 36 32 5d 20 5b 48 31 .** [H14162] [H1
a4f0: 34 31 36 35 5d 20 5b 48 31 34 31 36 38 5d 0a 2a 4165] [H14168].*
a500: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c /.SQLITE_API SQL
a510: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
a520: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e int sqlite3_con
a530: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a fig(int, ...);..
a540: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
a550: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 Configure databa
a560: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 se connections
a570: 7b 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30 30 {H14200} <S20000
a580: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
a590: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 L.**.** The sqli
a5a0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
a5b0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
a5c0: 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 d to make config
a5d0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
a5e0: 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 es to a [databas
a5f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
a600: 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 The interface is
a610: 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b similar to.** [
a620: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
a630: 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 ] except that th
a640: 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 e changes apply
a650: 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b to a single.** [
a660: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
a670: 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 ion] (specified
a680: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
a690: 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 ument). The.**
a6a0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
a6b0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 g() interface ca
a6c0: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 n only be used i
a6d0: 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 mmediately after
a6e0: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
a6f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
a700: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 reated using [sq
a710: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a lite3_open()],.*
a720: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 * [sqlite3_open1
a730: 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 6()], or [sqlite
a740: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 3_open_v2()]. .
a750: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
a760: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
a770: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 ite3_db_config(D
a780: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a ,V,...) is the.
a790: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
a7a0: 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 verb - an integ
a7b0: 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 er code that ind
a7c0: 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 icates what.** a
a7d0: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 spect of the [da
a7e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
a7f0: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 n] is being conf
a800: 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f igured..** The o
a810: 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 nly choice for t
a820: 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 his value is [SQ
a830: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
a840: 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 OKASIDE]..** New
a850: 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c verbs are likel
a860: 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e y to be added in
a870: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
a880: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 of SQLite..** A
a890: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
a8a0: 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 nts depend on th
a8b0: 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65 e verb..**.** Re
a8c0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
a8d0: 48 31 34 32 30 33 5d 20 5b 48 31 34 32 30 36 5d H14203] [H14206]
a8e0: 20 5b 48 31 34 32 30 39 5d 20 5b 48 31 34 32 31 [H14209] [H1421
a8f0: 32 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f 0a 53 2] [H14215].*/.S
a900: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
a910: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
a920: 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e t sqlite3_db_con
a930: 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e fig(sqlite3*, in
a940: 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a t op, ...);../*.
a950: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
a960: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 ory Allocation R
a970: 6f 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d outines {H10155}
a980: 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 <S20120>.** EXP
a990: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
a9a0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
a9b0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e his object defin
a9c0: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
a9d0: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a between SQLite.
a9e0: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c ** and low-level
a9f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
aa00: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a on routines..**.
aa10: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 ** This object i
aa20: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f s used in only o
aa30: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 ne place in the
aa40: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
aa50: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 ..** A pointer t
aa60: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
aa70: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 this object is
aa80: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a the argument to.
aa90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
aaa0: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 ig()] when the c
aab0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
aac0: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 ion is.** [SQLIT
aad0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
aae0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
aaf0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 IG_GETMALLOC].
ab00: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 .** By creating
ab10: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
ab20: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e his object.** an
ab30: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 d passing it to
ab40: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
ab50: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ([SQLITE_CONFIG_
ab60: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 MALLOC]).** duri
ab70: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
ab80: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
ab90: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 can specify an
aba0: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d alternative.** m
abb0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
abc0: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 subsystem for S
abd0: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 QLite to use for
abe0: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 all of its.** d
abf0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 ynamic memory ne
ac00: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 eds..**.** Note
ac10: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 that SQLite come
ac20: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b s with several [
ac30: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
ac40: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 allocators].** t
ac50: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c hat are perfectl
ac60: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 y adequate for t
ac70: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 he overwhelming
ac80: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c majority of appl
ac90: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 ications.** and
aca0: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 that this object
acb0: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 is only useful
acc0: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 to a tiny minori
acd0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
ace0: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 ns.** with speci
acf0: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c alized memory al
ad00: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 location require
ad10: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a ments. This obj
ad20: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 ect is.** also u
ad30: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 sed during testi
ad40: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 ng of SQLite in
ad50: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 order to specify
ad60: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a an alternative.
ad70: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
ad80: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 tor that simulat
ad90: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 es memory out-of
ada0: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f -memory conditio
adb0: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 ns in.** order t
adc0: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 o verify that SQ
add0: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 Lite recovers gr
ade0: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 acefully from su
adf0: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 ch.** conditions
ae00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c ..**.** The xMal
ae10: 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 loc and xFree me
ae20: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 thods must work
ae30: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c like the.** mall
ae40: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
ae50: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 functions from t
ae60: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
ae70: 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 brary..** The xR
ae80: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 ealloc method mu
ae90: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 st work like rea
aea0: 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 lloc() from the
aeb0: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
aec0: 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 ry.** with the e
aed0: 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 xception that if
aee0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
aef0: 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 ment to xRealloc
af00: 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 is zero,.** xRe
af10: 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 alloc must be a
af20: 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 no-op - it must
af30: 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 not perform any
af40: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a allocation or.**
af50: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 deallocation.
af60: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 SQLite guarantee
af70: 64 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f ds that the seco
af80: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
af90: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c * xRealloc is al
afa0: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 ways a value ret
afb0: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 urned by a prior
afc0: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 call to xRoundu
afd0: 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 p..** And so in
afe0: 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 cases where xRou
aff0: 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 ndup always retu
b000: 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e rns a positive n
b010: 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c umber,.** xReall
b020: 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 oc can perform e
b030: 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 xactly as the st
b040: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 andard library r
b050: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 ealloc() and.**
b060: 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 still be in comp
b070: 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 liance with this
b080: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a specification..
b090: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 **.** xSize shou
b0a0: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c ld return the al
b0b0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 located size of
b0c0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
b0d0: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c ion.** previousl
b0e0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
b0f0: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c xMalloc or xReal
b100: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 loc. The alloca
b110: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 ted size.** is a
b120: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 lways at least a
b130: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 s big as the req
b140: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 uested size but
b150: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a may be larger..*
b160: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 *.** The xRoundu
b170: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 p method returns
b180: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 what would be t
b190: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
b1a0: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 e of.** a memory
b1b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 allocation give
b1c0: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 n a particular r
b1d0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 equested size.
b1e0: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 Most memory.** a
b1f0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
b200: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 up memory alloca
b210: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 tions at least t
b220: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 o the next multi
b230: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f ple.** of 8. So
b240: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f me allocators ro
b250: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 und up to a larg
b260: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 er multiple or t
b270: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a o a power of 2..
b280: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 ** Every memory
b290: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 allocation reque
b2a0: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 st coming in thr
b2b0: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 ough [sqlite3_ma
b2c0: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 lloc()].** or [s
b2d0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
b2e0: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 ] first calls xR
b2f0: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 oundup. If xRou
b300: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 ndup returns 0,
b310: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 .** that causes
b320: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
b330: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 g memory allocat
b340: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a ion to fail..**.
b350: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 ** The xInit met
b360: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 hod initializes
b370: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
b380: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d ator. (For exam
b390: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 ple,.** it might
b3a0: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 allocate any re
b3b0: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 quire mutexes or
b3c0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 initialize inte
b3d0: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 rnal data.** str
b3e0: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 uctures. The xS
b3f0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 hutdown method i
b400: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 s invoked (indir
b410: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 ectly) by.** [sq
b420: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
b430: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 ] and should dea
b440: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f llocate any reso
b450: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a urces acquired.*
b460: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 * by xInit. The
b470: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 pAppData pointe
b480: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 r is used as the
b490: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 only parameter
b4a0: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 to.** xInit and
b4b0: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a xShutdown..**.**
b4c0: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 SQLite holds th
b4d0: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f e [SQLITE_MUTEX_
b4e0: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d STATIC_MASTER] m
b4f0: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 utex when it inv
b500: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 okes.** the xIni
b510: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 t method, so the
b520: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 xInit method ne
b530: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 ed not be thread
b540: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 safe. The.** xS
b550: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 hutdown method i
b560: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 s only called fr
b570: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 om [sqlite3_shut
b580: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f down()] so it do
b590: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 es.** not need t
b5a0: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 o be threadsafe
b5b0: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c either. For all
b5c0: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 other methods,
b5d0: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 SQLite.** holds
b5e0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 the [SQLITE_MUTE
b5f0: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 X_STATIC_MEM] mu
b600: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 tex as long as t
b610: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f he.** [SQLITE_CO
b620: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 NFIG_MEMSTATUS]
b630: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
b640: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f tion is turned o
b650: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 n (which.** it i
b660: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e s by default) an
b670: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 d so the methods
b680: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c are automatical
b690: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a ly serialized..*
b6a0: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 * However, if [S
b6b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
b6c0: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 STATUS] is disab
b6d0: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 led, then the ot
b6e0: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d her.** methods m
b6f0: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 ust be threadsaf
b700: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 e or else make t
b710: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 heir own arrange
b720: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 ments for.** ser
b730: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a ialization..**.*
b740: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 * SQLite will ne
b750: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 ver invoke xInit
b760: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 () more than onc
b770: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 e without an int
b780: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c ervening.** call
b790: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e to xShutdown().
b7a0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
b7b0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ct sqlite3_mem_m
b7c0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d ethods sqlite3_m
b7d0: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 em_methods;.stru
b7e0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ct sqlite3_mem_m
b7f0: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 ethods {. void
b800: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 *(*xMalloc)(int)
b810: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d ; /* Mem
b820: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
b830: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 unction */. voi
b840: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a d (*xFree)(void*
b850: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 ); /* F
b860: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f ree a prior allo
b870: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 cation */. void
b880: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f *(*xRealloc)(vo
b890: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 id*,int); /* Re
b8a0: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 size an allocati
b8b0: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 on */. int (*xS
b8c0: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 ize)(void*);
b8d0: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e /* Return
b8e0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 the size of an
b8f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
b900: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 int (*xRoundup)(
b910: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f int); /
b920: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 * Round up reque
b930: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 st size to alloc
b940: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 ation size */.
b950: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 int (*xInit)(voi
b960: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f d*); /
b970: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 * Initialize the
b980: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
b990: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 r */. void (*xS
b9a0: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b hutdown)(void*);
b9b0: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 /* Deiniti
b9c0: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
b9d0: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
b9e0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 void *pAppData;
b9f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
ba00: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 * Argument to xI
ba10: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 nit() and xShutd
ba20: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a own() */.};../*.
ba30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
ba40: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f figuration Optio
ba50: 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 ns {H10160} <S20
ba60: 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 000>.** EXPERIME
ba70: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 NTAL.**.** These
ba80: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 constants are t
ba90: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 he available int
baa0: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 eger configurati
bab0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a on options that.
bac0: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 ** can be passed
bad0: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
bae0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 gument to the [s
baf0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
bb00: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
bb10: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 * New configurat
bb20: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 ion options may
bb30: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
bb40: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
bb50: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 QLite..** Existi
bb60: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
bb70: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 options might b
bb80: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 e discontinued.
bb90: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a Applications.**
bba0: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 should check th
bbb0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 e return code fr
bbc0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 om [sqlite3_conf
bbd0: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 ig()] to make su
bbe0: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 re that.** the c
bbf0: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 all worked. The
bc00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
bc10: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
bc20: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
bc30: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
bc40: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
bc50: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
bc60: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
bc70: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
bc80: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
bc90: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
bca0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
bcb0: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c THREAD</dt>.** <
bcc0: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
bcd0: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
bce0: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 s option. This
bcf0: 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a option disables.
bd00: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 ** all mutexing
bd10: 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 and puts SQLite
bd20: 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 into a mode wher
bd30: 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 e it can only be
bd40: 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 used.** by a si
bd50: 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 ngle thread.</dd
bd60: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
bd70: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
bd80: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 HREAD</dt>.** <d
bd90: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
bda0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
bdb0: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f option. This o
bdc0: 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a ption disables.*
bdd0: 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 * mutexing on [d
bde0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
bdf0: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
be00: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
be10: 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ects..** The app
be20: 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 lication is resp
be30: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 onsible for seri
be40: 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 alizing access t
be50: 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 o.** [database c
be60: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
be70: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
be80: 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 ents]. But othe
be90: 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 r mutexes.** are
bea0: 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 enabled so that
beb0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 SQLite will be
bec0: 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 safe to use in a
bed0: 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a multi-threaded.
bee0: 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 ** environment a
bef0: 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f s long as no two
bf00: 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 threads attempt
bf10: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 to use the same
bf20: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
bf30: 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 nnection] at the
bf40: 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 same time. See
bf50: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
bf60: 6d 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e mode].** documen
bf70: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 tation for addit
bf80: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
bf90: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
bfa0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
bfb0: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a SERIALIZED</dt>.
bfc0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
bfd0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
bfe0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 this option. T
bff0: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c his option enabl
c000: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 es.** all mutexe
c010: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 s including the
c020: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 recursive.** mut
c030: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 exes on [databas
c040: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
c050: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
c060: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
c070: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 ** In this mode
c080: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 (which is the de
c090: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 fault when SQLit
c0a0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
c0b0: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 th.** [SQLITE_TH
c0c0: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 READSAFE=1]) the
c0d0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
c0e0: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 will itself seri
c0f0: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 alize access.**
c100: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e to [database con
c110: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 nections] and [p
c120: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
c130: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a ts] so that the.
c140: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 ** application i
c150: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 s free to use th
c160: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
c170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 connection] or
c180: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 the.** same [pre
c190: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
c1a0: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 in different th
c1b0: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
c1c0: 65 20 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 e time..** See t
c1d0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
c1e0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f de] documentatio
c1f0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c n for additional
c200: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 information.</d
c210: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
c220: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
c230: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 C</dt>.** <dd>Th
c240: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
c250: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
c260: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
c270: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
c280: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
c290: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
c2a0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
c2b0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
c2c0: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e cifies.** altern
c2d0: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
c2e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
c2f0: 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 n routines to be
c300: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f used in place o
c310: 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 f.** the memory
c320: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
c330: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
c340: 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a QLite.</dd>.**.*
c350: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
c360: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 FIG_GETMALLOC</d
c370: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
c380: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
c390: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
c3a0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
c3b0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
c3c0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
c3d0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 e3_mem_methods]
c3e0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 structure. The
c3f0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
c400: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 hods].** structu
c410: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 re is filled wit
c420: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 h the currently
c430: 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 defined memory a
c440: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
c450: 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 es..** This opti
c460: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 on can be used t
c470: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 o overload the d
c480: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c efault memory al
c490: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 location.** rout
c4a0: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 ines with a wrap
c4b0: 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 per that simulat
c4c0: 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ions memory allo
c4d0: 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f cation failure o
c4e0: 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f r.** tracks memo
c4f0: 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 ry usage, for ex
c500: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ample.</dd>.**.*
c510: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
c520: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 FIG_MEMSTATUS</d
c530: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
c540: 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 ption takes sing
c550: 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 le argument of t
c560: 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 ype int, interpr
c570: 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f eted as a .** bo
c580: 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 olean, which ena
c590: 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
c5a0: 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 the collection
c5b0: 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 of memory alloca
c5c0: 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 tion .** statist
c5d0: 69 63 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c ics. When disabl
c5e0: 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ed, the followin
c5f0: 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 g SQLite interfa
c600: 63 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e ces become .** n
c610: 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a on-operational:.
c620: 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c ** <ul>.** <
c630: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d li> [sqlite3_mem
c640: 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 ory_used()].**
c650: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
c660: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
c670: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
c680: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
c690: 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c limit()].** <l
c6a0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 i> [sqlite3_stat
c6b0: 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e us()].** </ul>
c6c0: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
c6d0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
c6e0: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a G_SCRATCH</dt>.*
c6f0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
c700: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
c710: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
c720: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 er that SQLite c
c730: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 an use for.** sc
c740: 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 ratch memory. T
c750: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
c760: 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 rguments: A poi
c770: 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a nter an 8-byte.*
c780: 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 * aligned memory
c790: 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 buffer from whi
c7a0: 63 68 20 74 68 65 20 73 63 72 61 63 68 20 61 6c ch the scrach al
c7b0: 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 locations will b
c7c0: 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 e.** drawn, the
c7d0: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 size of each scr
c7e0: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 atch allocation
c7f0: 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 (sz),.** and the
c800: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
c810: 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 of scratch alloc
c820: 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 ations (N). The
c830: 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 sz.** argument
c840: 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 must be a multip
c850: 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a le of 16. The sz
c860: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c parameter shoul
c870: 64 20 62 65 20 61 20 66 65 77 20 62 79 74 65 73 d be a few bytes
c880: 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 .** larger than
c890: 74 68 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 the actual scrat
c8a0: 63 68 20 73 70 61 63 65 20 72 65 71 75 69 72 65 ch space require
c8b0: 64 20 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 d due to interna
c8c0: 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 l overhead..** T
c8d0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
c8e0: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 t should pointer
c8f0: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c to an 8-byte al
c900: 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 igned buffer.**
c910: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e of at least sz*N
c920: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
c930: 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c ..** SQLite will
c940: 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 use no more tha
c950: 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 n one scratch bu
c960: 66 66 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 ffer at once per
c970: 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e thread, so.** N
c980: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 should be set t
c990: 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d o the expected m
c9a0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
c9b0: 20 74 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 threads. The s
c9c0: 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 z.** parameter s
c9d0: 68 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 hould be 6 times
c9e0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
c9f0: 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 largest databas
ca00: 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 e page size..**
ca10: 53 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 Scratch buffers
ca20: 61 72 65 20 75 73 65 64 20 61 73 20 70 61 72 74 are used as part
ca30: 20 6f 66 20 74 68 65 20 62 74 72 65 65 20 62 61 of the btree ba
ca40: 6c 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e lance operation.
ca50: 20 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 If.** The btre
ca60: 65 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 e balancer needs
ca70: 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f additional memo
ca80: 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 ry beyond what i
ca90: 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a s provided by.**
caa0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 scratch buffers
cab0: 20 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 or if no scratc
cac0: 68 20 62 75 66 66 65 72 20 73 70 61 63 65 20 69 h buffer space i
cad0: 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 s specified, the
cae0: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 n SQLite.** goes
caf0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
cb00: 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e loc()] to obtain
cb10: 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e the memory it n
cb20: 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a eeds.</dd>.**.**
cb30: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
cb40: 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 IG_PAGECACHE</dt
cb50: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
cb60: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
cb70: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 static memory b
cb80: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 uffer that SQLit
cb90: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a e can use for.**
cba0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 the database pa
cbb0: 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 ge cache with th
cbc0: 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 e default page c
cbd0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 ache implemenati
cbe0: 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f on. .** This co
cbf0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 nfiguration shou
cc00: 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 ld not be used i
cc10: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
cc20: 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 -define page.**
cc30: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
cc40: 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 tion is loaded u
cc50: 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f sing the SQLITE_
cc60: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 CONFIG_PCACHE op
cc70: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 tion..** There a
cc80: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
cc90: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
cca0: 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 n: A pointer to
ccb0: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 8-byte aligned.*
ccc0: 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 * memory, the si
ccd0: 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 ze of each page
cce0: 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 buffer (sz), and
ccf0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
cd00: 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 ages (N)..** The
cd10: 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f sz argument sho
cd20: 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 uld be the size
cd30: 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 of the largest d
cd40: 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 atabase page.**
cd50: 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 (a power of two
cd60: 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 between 512 and
cd70: 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 32768) plus a li
cd80: 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 ttle extra for e
cd90: 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 ach.** page head
cda0: 65 72 2e 20 20 54 68 65 20 70 61 67 65 20 68 65 er. The page he
cdb0: 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 ader size is 20
cdc0: 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 to 40 bytes depe
cdd0: 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 nding on.** the
cde0: 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 host architectur
cdf0: 65 2e 20 20 49 74 20 69 73 20 68 61 72 6d 6c 65 e. It is harmle
ce00: 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 ss, apart from t
ce10: 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 he wasted memory
ce20: 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 ,.** to make sz
ce30: 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 a little too lar
ce40: 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a ge. The first.*
ce50: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c * argument shoul
ce60: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c d point to an al
ce70: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c location of at l
ce80: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 east sz*N bytes
ce90: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 of memory..** SQ
cea0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 Lite will use th
ceb0: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 e memory provide
cec0: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 d by the first a
ced0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 rgument to satis
cee0: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 fy its.** memory
cef0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 needs for the f
cf00: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 irst N pages tha
cf10: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 t it adds to cac
cf20: 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e he. If addition
cf30: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 al.** page cache
cf40: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 memory is neede
cf50: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 d beyond what is
cf60: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 provided by thi
cf70: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a s option, then.*
cf80: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f * SQLite goes to
cf90: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
cfa0: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 ()] for the addi
cfb0: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 tional storage s
cfc0: 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 pace..** The imp
cfd0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 lementation migh
cfe0: 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 t use one or mor
cff0: 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 e of the N buffe
d000: 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d rs to hold .** m
d010: 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 emory accounting
d020: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 information. Th
d030: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 e pointer in the
d040: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
d050: 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e must.** be align
d060: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
d070: 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 boundary or subs
d080: 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
d090: 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c of SQLite.** wil
d0a0: 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
d0b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
d0c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
d0d0: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 P</dt>.** <dd>Th
d0e0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 is option specif
d0f0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
d100: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 ory buffer that
d110: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a SQLite will use.
d120: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 ** for all of it
d130: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 s dynamic memory
d140: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
d150: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 s beyond those p
d160: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 rovided.** for b
d170: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 y [SQLITE_CONFIG
d180: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 _SCRATCH] and [S
d190: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
d1a0: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 ECACHE]..** Ther
d1b0: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
d1c0: 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 ments: An 8-byte
d1d0: 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 aligned pointer
d1e0: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a to the memory,.
d1f0: 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
d200: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 bytes in the me
d210: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 mory buffer, and
d220: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
d230: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a ocation size..**
d240: 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f If the first po
d250: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
d260: 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 y pointer) is NU
d270: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 LL, then SQLite
d280: 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 reverts.** to us
d290: 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 ing its default
d2a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
d2b0: 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c (the system mal
d2c0: 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 loc() implementa
d2d0: 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e tion),.** undoin
d2e0: 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f g any prior invo
d2f0: 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 cation of [SQLIT
d300: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
d310: 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d . If the.** mem
d320: 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ory pointer is n
d330: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 ot NULL and eith
d340: 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c er [SQLITE_ENABL
d350: 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a E_MEMSYS3] or.**
d360: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
d370: 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 MEMSYS5] are def
d380: 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 ined, then the a
d390: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 lternative memor
d3a0: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 y.** allocator i
d3b0: 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e s engaged to han
d3c0: 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 dle all of SQLit
d3d0: 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 es memory alloca
d3e0: 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 tion needs..** T
d3f0: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 he first pointer
d400: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 (the memory poi
d410: 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c nter) must be al
d420: 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 igned to an 8-by
d430: 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f te.** boundary o
d440: 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 r subsequent beh
d450: 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 avior of SQLite
d460: 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 will be undefine
d470: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 d.</dd>.**.** <d
d480: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
d490: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
d4a0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
d4b0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
d4c0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
d4d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
d4e0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
d4f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
d500: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
d510: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ure. The argume
d520: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
d530: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
d540: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 level mutex rout
d550: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
d560: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 in place.** the
d570: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 mutex routines b
d580: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
d590: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
d5a0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
d5b0: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
d5c0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
d5d0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
d5e0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
d5f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
d600: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
d610: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
d620: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
d630: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b cture. The.** [
d640: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
d650: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 thods].** struct
d660: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 ure is filled wi
d670: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 th the currently
d680: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 defined mutex r
d690: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 outines..** This
d6a0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 option can be u
d6b0: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 sed to overload
d6c0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
d6d0: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 x allocation.**
d6e0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
d6f0: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 wrapper used to
d700: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 track mutex usag
d710: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 e for performanc
d720: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f e.** profiling o
d730: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 r testing, for e
d740: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a xample.</dd>.**.
d750: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
d760: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
d770: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
d780: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f option takes two
d790: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
d7a0: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 determine the de
d7b0: 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 fault.** memory
d7c0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 allocation looka
d7d0: 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f side optimizatio
d7e0: 6e 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 n. The first ar
d7f0: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
d800: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f size of each lo
d810: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 okaside buffer s
d820: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f lot and the seco
d830: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nd is the number
d840: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c of.** slots all
d850: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 ocated to each d
d860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
d870: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e on. This option
d880: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e sets the.** <i>
d890: 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b default</i> look
d8a0: 61 73 69 64 65 20 73 69 7a 65 2e 20 20 54 68 65 aside size. The
d8b0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 [SQLITE_DBCONFI
d8c0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 G_LOOKASIDE].**
d8d0: 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 verb to [sqlite3
d8e0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 _db_config()] ca
d8f0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 n be used to cha
d900: 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 nge the lookasid
d910: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 e.** configurati
d920: 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c on on individual
d930: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 3c 2f 64 connections.</d
d940: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
d950: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
d960: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 E</dt>.** <dd>Th
d970: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
d980: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
d990: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
d9a0: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 nter to.** an [s
d9b0: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
d9c0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 thods] object.
d9d0: 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 This object spec
d9e0: 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 ifies the interf
d9f0: 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 ace.** to a cust
da00: 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d om page cache im
da10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 plementation. S
da20: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
da30: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a py of the.** obj
da40: 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 ect and uses it
da50: 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d for page cache m
da60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
da70: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
da80: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
da90: 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a GETPCACHE</dt>.*
daa0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
dab0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
dac0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
dad0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
dae0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 an.** [sqlite3_p
daf0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f cache_methods] o
db00: 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 bject. SQLite c
db10: 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 opies of the cur
db20: 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 rent.** page cac
db30: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
db40: 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 n into that obje
db50: 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ct.</dd>.**.** <
db60: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
db70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
db80: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f NGLETHREAD 1 /
db90: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
dba0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
dbb0: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 ULTITHREAD 2
dbc0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
dbd0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
dbe0: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 SERIALIZED 3
dbf0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
dc00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
dc10: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 _MALLOC 4
dc20: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
dc30: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
dc40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
dc50: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 IG_GETMALLOC
dc60: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 5 /* sqlite3_m
dc70: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
dc80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
dc90: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 NFIG_SCRATCH
dca0: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 6 /* void*,
dcb0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f int sz, int N */
dcc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dcd0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
dce0: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 7 /* void*
dcf0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
dd00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
dd10: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 E_CONFIG_HEAP
dd20: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 8 /* voi
dd30: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 d*, int nByte, i
dd40: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e nt min */.#defin
dd50: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
dd60: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 MEMSTATUS 9
dd70: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 /* boolean */.#
dd80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
dd90: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 NFIG_MUTEX
dda0: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 10 /* sqlite3
ddb0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
ddc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
ddd0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
dde0: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c X 11 /* sql
ddf0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
de00: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f ds* */./* previo
de10: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 usly SQLITE_CONF
de20: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 IG_CHUNKALLOC 12
de30: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e which is now un
de40: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e used. */ .#defin
de50: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
de60: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 LOOKASIDE 13
de70: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 /* int int */.#
de80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
de90: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 NFIG_PCACHE
dea0: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 14 /* sqlite3
deb0: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a _pcache_methods*
dec0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
ded0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
dee0: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 CHE 15 /* sq
def0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
df00: 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 hods* */../*.**
df10: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
df20: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 uration Options
df30: 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 {H10170} <S20000
df40: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
df50: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f L.**.** These co
df60: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
df70: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
df80: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
df90: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
dfa0: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
dfb0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
dfc0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c ment to the [sql
dfd0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
dfe0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
dff0: 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 ** New configura
e000: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 tion options may
e010: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
e020: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
e030: 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 SQLite..** Exist
e040: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
e050: 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 n options might
e060: 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e be discontinued.
e070: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a Applications.*
e080: 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 * should check t
e090: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 he return code f
e0a0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f rom [sqlite3_db_
e0b0: 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b config()] to mak
e0c0: 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 e sure that.** t
e0d0: 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 he call worked.
e0e0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 The [sqlite3_db
e0f0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
e100: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e face will return
e110: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b a.** non-zero [
e120: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
e130: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
e140: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e unsupported con
e150: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
e160: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e n.** is invoked.
e170: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c .**.** <dl>.** <
e180: 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
e190: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 IG_LOOKASIDE</dt
e1a0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
e1b0: 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 tion takes three
e1c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
e1d0: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
e1e0: 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f mine the .** [lo
e1f0: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
e200: 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 llocator] config
e210: 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 uration for the
e220: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
e230: 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 tion]..** The fi
e240: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 rst argument (th
e250: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
e260: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 r to [sqlite3_db
e270: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a _config()] is a.
e280: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ** pointer to an
e290: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
e2a0: 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 o use for lookas
e2b0: 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 54 ide memory..** T
e2c0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
e2d0: 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e t may be NULL in
e2e0: 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 which case SQLi
e2f0: 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 te will allocate
e300: 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 the.** lookasid
e310: 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 e buffer itself
e320: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
e330: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 alloc()]. The s
e340: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
e350: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 s the.** size of
e360: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 each lookaside
e370: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 buffer slot and
e380: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
e390: 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nt is the number
e3a0: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 of.** slots. T
e3b0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 he size of the b
e3c0: 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 uffer in the fir
e3d0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 st argument must
e3e0: 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e be greater than
e3f0: 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 .** or equal to
e400: 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 the product of t
e410: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
e420: 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 ird arguments.
e430: 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 The buffer.** mu
e440: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f st be aligned to
e450: 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 an 8-byte bound
e460: 61 72 79 2e 20 20 49 66 20 74 68 65 20 73 65 63 ary. If the sec
e470: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
e480: 6e 6f 74 0a 2a 2a 20 61 20 6d 75 6c 74 69 70 6c not.** a multipl
e490: 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e e of 8, it is in
e4a0: 74 65 72 6e 61 6c 6c 79 20 72 6f 75 6e 64 65 64 ternally rounded
e4b0: 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 down to the nex
e4c0: 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c t smaller.** mul
e4d0: 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 tiple of 8. See
e4e0: 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 also: [SQLITE_C
e4f0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
e500: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c </dd>.**.** </dl
e510: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
e520: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
e530: 4b 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 KASIDE 1001
e540: 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 /* void* int int
e550: 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 */.../*.** CAPI
e560: 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 3REF: Enable Or
e570: 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 Disable Extended
e580: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 Result Codes {H
e590: 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 12200} <S10700>.
e5a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
e5b0: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
e5c0: 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e t_codes() routin
e5d0: 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 e enables or dis
e5e0: 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 ables the.** [ex
e5f0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
e600: 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 des] feature of
e610: 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 SQLite. The exte
e620: 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 nded result.** c
e630: 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 odes are disable
e640: 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 d by default for
e650: 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 historical comp
e660: 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 atibility consid
e670: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
e680: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
e690: 20 5b 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 [H12201] [H1220
e6a0: 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 2].*/.SQLITE_API
e6b0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 int sqlite3_ext
e6c0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
e6d0: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 es(sqlite3*, int
e6e0: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 onoff);../*.**
e6f0: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 CAPI3REF: Last I
e700: 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 nsert Rowid {H12
e710: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 220} <S10700>.**
e720: 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 .** Each entry i
e730: 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c n an SQLite tabl
e740: 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 e has a unique 6
e750: 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 4-bit signed.**
e760: 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c integer key call
e770: 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 ed the [ROWID |
e780: 22 72 6f 77 69 64 22 5d 2e 20 54 68 65 20 72 6f "rowid"]. The ro
e790: 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 wid is always av
e7a0: 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e ailable.** as an
e7b0: 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 undeclared colu
e7c0: 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 mn named ROWID,
e7d0: 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 OID, or _ROWID_
e7e0: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 as long as those
e7f0: 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f .** names are no
e800: 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 t also used by e
e810: 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
e820: 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a ed columns. If.*
e830: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 * the table has
e840: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 a column of type
e850: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 [INTEGER PRIMAR
e860: 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 Y KEY] then that
e870: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e column.** is an
e880: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 other alias for
e890: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a the rowid..**.**
e8a0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
e8b0: 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 turns the [rowid
e8c0: 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ] of the most re
e8d0: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 cent.** successf
e8e0: 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f ul [INSERT] into
e8f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 the database fr
e900: 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 om the [database
e910: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
e920: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
e930: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 ument. If no su
e940: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
e950: 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 ]s.** have ever
e960: 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 occurred on that
e970: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
e980: 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 tion, zero is re
e990: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 turned..**.** If
e9a0: 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 an [INSERT] occ
e9b0: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 urs within a tri
e9c0: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b gger, then the [
e9d0: 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e rowid] of the in
e9e0: 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 serted.** row is
e9f0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
ea00: 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e s routine as lon
ea10: 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 g as the trigger
ea20: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 is running..**
ea30: 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 But once the tri
ea40: 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c gger terminates,
ea50: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
ea60: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 ned by this rout
ea70: 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 ine.** reverts t
ea80: 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 o the last value
ea90: 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 inserted before
eaa0: 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 the trigger fir
eab0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e ed..**.** An [IN
eac0: 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 SERT] that fails
ead0: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 due to a constr
eae0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 aint violation i
eaf0: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 s not a.** succe
eb00: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 ssful [INSERT] a
eb10: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nd does not chan
eb20: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ge the value ret
eb30: 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a urned by this.**
eb40: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 routine. Thus
eb50: 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 INSERT OR FAIL,
eb60: 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 INSERT OR IGNORE
eb70: 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c , INSERT OR ROLL
eb80: 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 BACK,.** and INS
eb90: 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b ERT OR ABORT mak
eba0: 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 e no changes to
ebb0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
ebc0: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 of this.** rout
ebd0: 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 ine when their i
ebe0: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 nsertion fails.
ebf0: 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 When INSERT OR
ec00: 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 REPLACE.** encou
ec10: 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 nters a constrai
ec20: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 nt violation, it
ec30: 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 does not fail.
ec40: 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 The.** INSERT c
ec50: 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 ontinues to comp
ec60: 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c letion after del
ec70: 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 eting rows that
ec80: 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f caused.** the co
ec90: 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d nstraint problem
eca0: 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 so INSERT OR RE
ecb0: 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 PLACE will alway
ecc0: 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 s change.** the
ecd0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
ece0: 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a this interface..
ecf0: 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 **.** For the pu
ed00: 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 rposes of this r
ed10: 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 outine, an [INSE
ed20: 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 RT] is considere
ed30: 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 d to.** be succe
ed40: 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 ssful even if it
ed50: 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 is subsequently
ed60: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a rolled back..**
ed70: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
ed80: 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d 20 5b 48 :.** [H12221] [H
ed90: 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 12223].**.** If
eda0: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
edb0: 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 d performs a new
edc0: 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 [INSERT] on the
edd0: 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 same.** databas
ede0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 e connection whi
edf0: 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f le the [sqlite3_
ee00: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
ee10: 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e d()].** function
ee20: 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 is running and
ee30: 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 thus changes the
ee40: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f last insert [ro
ee50: 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 wid],.** then th
ee60: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
ee70: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 by [sqlite3_las
ee80: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
ee90: 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 ] is.** unpredic
eea0: 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 table and might
eeb0: 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 not equal either
eec0: 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 the old or the
eed0: 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 new.** last inse
eee0: 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 rt [rowid]..*/.S
eef0: 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
ef00: 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
ef10: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
ef20: 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a d(sqlite3*);../*
ef30: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
ef40: 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f unt The Number O
ef50: 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 f Rows Modified
ef60: 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30 30 {H12240} <S10600
ef70: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e >.**.** This fun
ef80: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
ef90: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 e number of data
efa0: 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 base rows that w
efb0: 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f ere changed.** o
efc0: 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 r inserted or de
efd0: 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 leted by the mos
efe0: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c t recently compl
eff0: 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 eted SQL stateme
f000: 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 nt.** on the [da
f010: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
f020: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 n] specified by
f030: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
f040: 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 ter..** Only cha
f050: 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 nges that are di
f060: 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 rectly specified
f070: 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d by the [INSERT]
f080: 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f , [UPDATE],.** o
f090: 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
f0a0: 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 ment are counted
f0b0: 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 . Auxiliary cha
f0c0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a nges caused by.*
f0d0: 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 * triggers or [f
f0e0: 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
f0f0: 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e ns] are not coun
f100: 74 65 64 2e 20 55 73 65 20 74 68 65 0a 2a 2a 20 ted. Use the.**
f110: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
f120: 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 hanges()] functi
f130: 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 on to find the t
f140: 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 otal number of c
f150: 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 hanges.** includ
f160: 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 ing changes caus
f170: 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 ed by triggers a
f180: 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 nd foreign key a
f190: 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 68 ctions..**.** Ch
f1a0: 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 anges to a view
f1b0: 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 that are simulat
f1c0: 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 ed by an [INSTEA
f1d0: 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a D OF trigger].**
f1e0: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
f1f0: 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 . Only real tab
f200: 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 le changes are c
f210: 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 20 ounted..**.** A
f220: 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 "row change" is
f230: 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 a change to a si
f240: 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 ngle row of a si
f250: 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 ngle table.** ca
f260: 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 used by an INSER
f270: 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 T, DELETE, or UP
f280: 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 DATE statement.
f290: 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 Rows that.** ar
f2a0: 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 e changed as sid
f2b0: 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 e effects of [RE
f2c0: 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e PLACE] constrain
f2d0: 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a t resolution,.**
f2e0: 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 rollback, ABORT
f2f0: 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 processing, [DR
f300: 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 OP TABLE], or by
f310: 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 any other.** me
f320: 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 chanisms do not
f330: 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 count as direct
f340: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a row changes..**.
f350: 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f ** A "trigger co
f360: 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 ntext" is a scop
f370: 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 e of execution t
f380: 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a hat begins and.*
f390: 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 * ends with the
f3a0: 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 script of a [CRE
f3b0: 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 ATE TRIGGER | tr
f3c0: 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 igger]. .** Most
f3d0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
f3e0: 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 are.** evaluated
f3f0: 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 outside of any
f400: 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 trigger. This i
f410: 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c s the "top level
f420: 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e ".** trigger con
f430: 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 text. If a trig
f440: 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 ger fires from t
f450: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a he top level, a.
f460: 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 ** new trigger c
f470: 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 ontext is entere
f480: 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 d for the durati
f490: 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a on of that one.*
f4a0: 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 * trigger. Subt
f4b0: 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 riggers create s
f4c0: 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 ubcontexts for t
f4d0: 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a heir duration..*
f4e0: 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 *.** Calling [sq
f4f0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 lite3_exec()] or
f500: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
f510: 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f ] recursively do
f520: 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 es.** not create
f530: 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 a new trigger c
f540: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 ontext..**.** Th
f550: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
f560: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
f570: 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 f direct row cha
f580: 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d nges in the.** m
f590: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 ost recent INSER
f5a0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
f5b0: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 LETE statement w
f5c0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a ithin the same.*
f5d0: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 * trigger contex
f5e0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 t..**.** Thus, w
f5f0: 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 hen called from
f600: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 the top level, t
f610: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
f620: 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 urns the.** numb
f630: 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e er of changes in
f640: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
f650: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
f660: 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 or DELETE.** th
f670: 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 at also occurred
f680: 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 at the top leve
f690: 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 l. Within the b
f6a0: 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 ody of a trigger
f6b0: 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 ,.** the sqlite3
f6c0: 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 _changes() inter
f6d0: 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c face can be call
f6e0: 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e ed to find the n
f6f0: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e umber of.** chan
f700: 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 ges in the most
f710: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 recently complet
f720: 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 ed INSERT, UPDAT
f730: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
f740: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e statement within
f750: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 the body of the
f760: 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a same trigger..*
f770: 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e * However, the n
f780: 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 umber returned d
f790: 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
f7a0: 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 changes.** cause
f7b0: 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 d by subtriggers
f7c0: 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 since those hav
f7d0: 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 e their own cont
f7e0: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ext..**.** See a
f7f0: 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
f800: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
f810: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 ] interface and
f820: 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 the.** [count_ch
f830: 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2e 0a 2a anges pragma]..*
f840: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
f850: 73 3a 0a 2a 2a 20 5b 48 31 32 32 34 31 5d 20 5b s:.** [H12241] [
f860: 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 H12243].**.** If
f870: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
f880: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 ad makes changes
f890: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
f8a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
f8b0: 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 .** while [sqlit
f8c0: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 e3_changes()] is
f8d0: 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 running then th
f8e0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
f8f0: 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 .** is unpredict
f900: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 able and not mea
f910: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 ningful..*/.SQLI
f920: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
f930: 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 e3_changes(sqlit
f940: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
f950: 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d I3REF: Total Num
f960: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 ber Of Rows Modi
f970: 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 fied {H12260} <S
f980: 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 10600>.**.** Thi
f990: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
f9a0: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
f9b0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 row changes cau
f9c0: 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c sed by [INSERT],
f9d0: 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 .** [UPDATE] or
f9e0: 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 [DELETE] stateme
f9f0: 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 nts since the [d
fa00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
fa10: 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a on] was opened..
fa20: 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 ** The count inc
fa30: 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 ludes all change
fa40: 73 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 s from all [CREA
fa50: 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
fa60: 67 67 65 72 5d 20 0a 2a 2a 20 63 6f 6e 74 65 78 gger] .** contex
fa70: 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d ts and changes m
fa80: 61 64 65 20 62 79 20 5b 66 6f 72 65 69 67 6e 20 ade by [foreign
fa90: 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f key actions]. Ho
faa0: 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f wever,.** the co
fab0: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 unt does not inc
fac0: 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 lude changes use
fad0: 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b d to implement [
fae0: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 REPLACE] constra
faf0: 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c ints,.** do roll
fb00: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 backs or ABORT p
fb10: 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 rocessing, or [D
fb20: 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 ROP TABLE] proce
fb30: 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 ssing. The.** c
fb40: 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e ount does not in
fb50: 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 clude rows of vi
fb60: 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e ews that fire an
fb70: 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 [INSTEAD OF tri
fb80: 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 gger],.** though
fb90: 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 if the INSTEAD
fba0: 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 OF trigger makes
fbb0: 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 changes of its
fbc0: 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 own, those chang
fbd0: 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 es .** are count
fbe0: 65 64 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 ed..** The chang
fbf0: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 es are counted a
fc00: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 s soon as the st
fc10: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b atement that mak
fc20: 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f es them is.** co
fc30: 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 mpleted (when th
fc40: 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 e statement hand
fc50: 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 le is passed to
fc60: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
fc70: 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
fc80: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a _finalize()])..*
fc90: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
fca0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
fcb0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 es()] interface
fcc0: 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e and the.** [coun
fcd0: 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 t_changes pragma
fce0: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 ]..**.** Require
fcf0: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36 ments:.** [H1226
fd00: 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a 1] [H12263].**.*
fd10: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
fd20: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 thread makes cha
fd30: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 nges on the same
fd40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
fd50: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 tion.** while [s
fd60: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
fd70: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 nges()] is runni
fd80: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 ng then the valu
fd90: 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 e.** returned is
fda0: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
fdb0: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 nd not meaningfu
fdc0: 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 l..*/.SQLITE_API
fdd0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 int sqlite3_tot
fde0: 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 al_changes(sqlit
fdf0: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
fe00: 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 I3REF: Interrupt
fe10: 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 A Long-Running
fe20: 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d 20 3c Query {H12270} <
fe30: 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30500>.**.** Th
fe40: 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 is function caus
fe50: 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 es any pending d
fe60: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
fe70: 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a n to abort and.*
fe80: 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 * return at its
fe90: 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 earliest opportu
fea0: 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 nity. This routi
feb0: 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a ne is typically.
fec0: 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 ** called in res
fed0: 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 ponse to a user
fee0: 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 action such as p
fef0: 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 ressing "Cancel"
ff00: 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 .** or Ctrl-C wh
ff10: 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e ere the user wan
ff20: 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 ts a long query
ff30: 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c operation to hal
ff40: 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 t.** immediately
ff50: 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 ..**.** It is sa
ff60: 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
ff70: 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 routine from a t
ff80: 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 hread different
ff90: 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 from the.** thre
ffa0: 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 ad that is curre
ffb0: 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 ntly running the
ffc0: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 database operat
ffd0: 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 ion. But it.**
ffe0: 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 is not safe to c
fff0: 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 all this routine
10000 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 with a [databas
10010 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 e connection] th
10020 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 at.** is closed
10030 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 or might close b
10040 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e efore sqlite3_in
10050 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e terrupt() return
10060 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 s..**.** If an S
10070 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 QL operation is
10080 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 very nearly fini
10090 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 shed at the time
100a0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 when.** sqlite3
100b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 _interrupt() is
100c0 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 called, then it
100d0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 might not have a
100e0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a n opportunity.**
100f0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 to be interrupt
10100 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e ed and might con
10110 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 tinue to complet
10120 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 ion..**.** An SQ
10130 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 L operation that
10140 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 is interrupted
10150 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c will return [SQL
10160 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a ITE_INTERRUPT]..
10170 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 ** If the interr
10180 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 upted SQL operat
10190 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 ion is an INSERT
101a0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
101b0 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ETE.** that is i
101c0 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 nside an explici
101d0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 t transaction, t
101e0 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 hen the entire t
101f0 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 ransaction.** wi
10200 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 ll be rolled bac
10210 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e k automatically.
10220 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
10230 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 e3_interrupt(D)
10240 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 call is in effec
10250 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 t until all curr
10260 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a ently running.**
10270 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
10280 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
10290 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c nection] D compl
102a0 65 74 65 2e 20 20 41 6e 79 20 6e 65 77 20 53 51 ete. Any new SQ
102b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
102c0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
102d0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 after the sqlit
102e0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
102f0 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 all and before t
10300 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 he .** running s
10310 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 tatements reache
10320 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 s zero are inter
10330 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 rupted as if the
10340 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 y had been.** ru
10350 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 nning prior to t
10360 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
10370 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 4e 65 rupt() call. Ne
10380 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 w SQL statements
10390 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
103a0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 rted after the r
103b0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 unning statement
103c0 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a count reaches z
103d0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 ero are.** not e
103e0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 ffected by the s
103f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
10400 28 29 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f ()..** A call to
10410 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
10420 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 pt(D) that occur
10430 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 s when there are
10440 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 no running.** S
10450 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 QL statements is
10460 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 a no-op and has
10470 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 no effect on SQ
10480 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
10490 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
104a0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 after the sqlit
104b0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
104c0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a all returns..**.
104d0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
104e0 0a 2a 2a 20 5b 48 31 32 32 37 31 5d 20 5b 48 31 .** [H12271] [H1
104f0 32 32 37 32 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 2272].**.** If t
10500 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
10510 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 ection closes wh
10520 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 ile [sqlite3_int
10530 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 errupt()].** is
10540 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 running then bad
10550 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b things will lik
10560 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 ely happen..*/.S
10570 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
10580 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
10590 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
105a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
105b0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
105c0 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f Statement Is Co
105d0 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20 mplete {H10510}
105e0 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S70200>.**.** T
105f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
10600 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 e useful during
10610 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 command-line inp
10620 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ut to determine
10630 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e if the.** curren
10640 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 tly entered text
10650 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 seems to form a
10660 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 complete SQL st
10670 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 atement or.** if
10680 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 additional inpu
10690 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f t is needed befo
106a0 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 re sending the t
106b0 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 ext into.** SQLi
106c0 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 te for parsing.
106d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
106e0 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 return 1 if the
106f0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 input string.**
10700 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 appears to be a
10710 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
10720 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 tement. A state
10730 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 ment is judged t
10740 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 o be.** complete
10750 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 if it ends with
10760 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b a semicolon tok
10770 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 en and is not a
10780 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 prefix of a.** w
10790 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 ell-formed CREAT
107a0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d E TRIGGER statem
107b0 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 ent. Semicolons
107c0 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 that are embedd
107d0 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 ed within.** str
107e0 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 ing literals or
107f0 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 quoted identifie
10800 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 r names or comme
10810 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 nts are not.** i
10820 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e ndependent token
10830 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 s (they are part
10840 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e of the token in
10850 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a which they are.
10860 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 ** embedded) and
10870 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 thus do not cou
10880 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e nt as a statemen
10890 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 57 t terminator. W
108a0 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 hitespace.** and
108b0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 comments that f
108c0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 ollow the final
108d0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 semicolon are ig
108e0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 nored..**.** The
108f0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
10900 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 rn 0 if the stat
10910 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c ement is incompl
10920 65 74 65 2e 20 20 49 66 20 61 0a 2a 2a 20 6d 65 ete. If a.** me
10930 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
10940 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 fails, then SQLI
10950 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 TE_NOMEM is retu
10960 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 rned..**.** Thes
10970 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f e routines do no
10980 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 t parse the SQL
10990 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a statements thus.
109a0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 ** will not dete
109b0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 ct syntactically
109c0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a incorrect SQL..
109d0 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 **.** If SQLite
109e0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 has not been ini
109f0 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b tialized using [
10a00 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
10a10 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 ze()] prior .**
10a20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 to invoking sqli
10a30 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
10a40 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e then sqlite3_in
10a50 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e itialize() is in
10a60 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 voked.** automat
10a70 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 ically by sqlite
10a80 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 3_complete16().
10a90 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c If that initial
10aa0 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a ization fails,.*
10ab0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 * then the retur
10ac0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c n value from sql
10ad0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
10ae0 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 ) will be non-ze
10af0 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 ro.** regardless
10b00 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
10b10 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c ot the input SQL
10b20 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 0a 2a 2a is complete..**
10b30 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
10b40 3a 20 5b 48 31 30 35 31 31 5d 20 5b 48 31 30 35 : [H10511] [H105
10b50 31 32 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 12].**.** The in
10b60 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
10b70 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 complete()] must
10b80 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
10b90 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 nated.** UTF-8 s
10ba0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tring..**.** The
10bb0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
10bc0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d e3_complete16()]
10bd0 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d must be a zero-
10be0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 terminated.** UT
10bf0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e F-16 string in n
10c00 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
10c10 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
10c20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 int sqlite3_comp
10c30 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 lete(const char
10c40 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 *sql);.SQLITE_AP
10c50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f I int sqlite3_co
10c60 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 mplete16(const v
10c70 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a oid *sql);../*.*
10c80 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 * CAPI3REF: Regi
10c90 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 ster A Callback
10ca0 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 To Handle SQLITE
10cb0 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 _BUSY Errors {H1
10cc0 32 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2310} <S40400>.*
10cd0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
10ce0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 e sets a callbac
10cf0 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 k function that
10d00 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 might be invoked
10d10 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 whenever.** an
10d20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 attempt is made
10d30 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 to open a databa
10d40 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e se table that an
10d50 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 other thread.**
10d60 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c or process has l
10d70 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ocked..**.** If
10d80 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 the busy callbac
10d90 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 k is NULL, then
10da0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 [SQLITE_BUSY] or
10db0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
10dc0 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 LOCKED].** is re
10dd0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
10de0 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 ly upon encounte
10df0 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 ring the lock. I
10e00 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 f the busy callb
10e10 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 ack.** is not NU
10e20 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c LL, then the cal
10e30 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e lback will be in
10e40 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 voked with two a
10e50 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 rguments..**.**
10e60 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
10e70 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 nt to the handle
10e80 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 r is a copy of t
10e90 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 he void* pointer
10ea0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 which.** is the
10eb0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
10ec0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f to sqlite3_busy_
10ed0 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 handler(). The
10ee0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
10ef0 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 to.** the handle
10f00 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 r callback is th
10f10 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 e number of time
10f20 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 s that the busy
10f30 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 handler has.** b
10f40 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 een invoked for
10f50 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 this locking eve
10f60 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 nt. If the.** b
10f70 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 usy callback ret
10f80 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 urns 0, then no
10f90 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d additional attem
10fa0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a pts are made to.
10fb0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 ** access the da
10fc0 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 tabase and [SQLI
10fd0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c TE_BUSY] or [SQL
10fe0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
10ff0 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a D] is returned..
11000 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 ** If the callba
11010 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
11020 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 ero, then anothe
11030 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 r attempt.** is
11040 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 made to open the
11050 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 database for re
11060 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 ading and the cy
11070 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a cle repeats..**.
11080 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 ** The presence
11090 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 of a busy handle
110a0 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 r does not guara
110b0 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c ntee that it wil
110c0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 l be invoked.**
110d0 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f when there is lo
110e0 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 ck contention. I
110f0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 f SQLite determi
11100 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e nes that invokin
11110 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 g the busy.** ha
11120 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 ndler could resu
11130 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b lt in a deadlock
11140 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 , it will go ahe
11150 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 ad and return [S
11160 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f QLITE_BUSY].** o
11170 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
11180 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 BLOCKED] instead
11190 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 of invoking the
111a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
111b0 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 * Consider a sce
111c0 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 nario where one
111d0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
111e0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 ng a read lock t
111f0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 hat.** it is try
11200 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 ing to promote t
11210 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 o a reserved loc
11220 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e k and.** a secon
11230 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c d process is hol
11240 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 ding a reserved
11250 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 lock that it is
11260 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f trying.** to pro
11270 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 mote to an exclu
11280 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 sive lock. The
11290 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 first process ca
112a0 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 nnot proceed.**
112b0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c because it is bl
112c0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 ocked by the sec
112d0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f ond and the seco
112e0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f nd process canno
112f0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 t.** proceed bec
11300 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
11310 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e ed by the first.
11320 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 If both proces
11330 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 ses.** invoke th
11340 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c e busy handlers,
11350 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 neither will ma
11360 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e ke any progress.
11370 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 Therefore,.**
11380 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b SQLite returns [
11390 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 SQLITE_BUSY] for
113a0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
113b0 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 ss, hoping that
113c0 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 this.** will ind
113d0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 uce the first pr
113e0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 ocess to release
113f0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 its read lock a
11400 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 nd allow.** the
11410 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 second process t
11420 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a o proceed..**.**
11430 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 The default bus
11440 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
11450 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 LL..**.** The [S
11460 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f QLITE_BUSY] erro
11470 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 r is converted t
11480 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f o [SQLITE_IOERR_
11490 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e BLOCKED].** when
114a0 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 SQLite is in th
114b0 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 e middle of a la
114c0 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 rge transaction
114d0 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a where all the.**
114e0 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f changes will no
114f0 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 t fit into the i
11500 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 n-memory cache.
11510 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 SQLite will.**
11520 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 already hold a R
11530 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 ESERVED lock on
11540 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
11550 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a e, but it needs.
11560 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 ** to promote th
11570 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 is lock to EXCLU
11580 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 SIVE so that it
11590 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a can spill cache.
115a0 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 ** pages into th
115b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
115c0 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 without harm to
115d0 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 concurrent.** re
115e0 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 aders. If it is
115f0 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f unable to promo
11600 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 te the lock, the
11610 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a n the in-memory.
11620 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 ** cache will be
11630 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f left in an inco
11640 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 nsistent state a
11650 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a nd so the error.
11660 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f ** code is promo
11670 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c ted from the rel
11680 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b atively benign [
11690 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a SQLITE_BUSY] to.
116a0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 ** the more seve
116b0 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 re [SQLITE_IOERR
116c0 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 _BLOCKED]. This
116d0 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d error code prom
116e0 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 otion.** forces
116f0 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c an automatic rol
11700 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 lback of the cha
11710 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a nges. See the.*
11720 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 * <a href="/cvst
11730 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 rac/wiki?p=Corru
11740 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 ptionFollowingBu
11750 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 syError">.** Cor
11760 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 ruptionFollowing
11770 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 BusyError</a> wi
11780 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 ki page for a di
11790 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a scussion of why.
117a0 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 ** this is impor
117b0 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 tant..**.** Ther
117c0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
117d0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
117e0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 ler defined for
117f0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 each.** [databas
11800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
11810 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 Setting a new bu
11820 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 sy handler clear
11830 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 s any.** previou
11840 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e sly set handler.
11850 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c Note that call
11860 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 ing [sqlite3_bus
11870 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 y_timeout()].**
11880 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 will also set or
11890 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 clear the busy
118a0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 handler..**.** T
118b0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
118c0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 should not take
118d0 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 any actions whi
118e0 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a ch modify the.**
118f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
11900 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
11910 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c d the busy handl
11920 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 er. Any such ac
11930 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 tions.** result
11940 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
11950 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 52 65 avior..** .** Re
11960 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
11970 48 31 32 33 31 31 5d 20 5b 48 31 32 33 31 32 5d H12311] [H12312]
11980 20 5b 48 31 32 33 31 34 5d 20 5b 48 31 32 33 31 [H12314] [H1231
11990 36 5d 20 5b 48 31 32 33 31 38 5d 0a 2a 2a 0a 2a 6] [H12318].**.*
119a0 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 * A busy handler
119b0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 must not close
119c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
119d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 nection.** or [p
119e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
119f0 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 t] that invoked
11a00 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
11a10 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
11a20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 int sqlite3_busy
11a30 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
11a40 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
11a50 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
11a60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
11a70 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
11a80 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 t {H12340} <S404
11a90 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 10>.**.** This r
11aa0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 outine sets a [s
11ab0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
11ac0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c ler | busy handl
11ad0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a er] that sleeps.
11ae0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 ** for a specifi
11af0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d ed amount of tim
11b00 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 e when a table i
11b10 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 s locked. The h
11b20 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
11b30 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
11b40 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
11b50 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
11b60 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
11b70 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
11b80 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 ated. {H12343} A
11b90 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 fter "ms" millis
11ba0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
11bb0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c ng,.** the handl
11bc0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
11bd0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ch causes [sqlit
11be0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
11bf0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
11c00 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
11c10 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
11c20 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 .**.** Calling t
11c30 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
11c40 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 an argument les
11c50 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
11c60 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 to zero.** turns
11c70 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 off all busy ha
11c80 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ndlers..**.** Th
11c90 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
11ca0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
11cb0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
11cc0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
11cd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
11ce0 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f any any given mo
11cf0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 ment. If anothe
11d00 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a r busy handler.*
11d10 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 * was defined (
11d20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
11d30 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 usy_handler()])
11d40 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
11d50 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
11d60 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 , that other bus
11d70 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 y handler is cle
11d80 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ared..**.** Requ
11d90 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
11da0 32 33 34 31 5d 20 5b 48 31 32 33 34 33 5d 20 5b 2341] [H12343] [
11db0 48 31 32 33 34 34 5d 0a 2a 2f 0a 53 51 4c 49 54 H12344].*/.SQLIT
11dc0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
11dd0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 3_busy_timeout(s
11de0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 qlite3*, int ms)
11df0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
11e00 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 F: Convenience R
11e10 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e outines For Runn
11e20 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 ing Queries {H12
11e30 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 370} <S10000>.**
11e40 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 .** Definition:
11e50 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c A <b>result tabl
11e60 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 e</b> is memory
11e70 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 data structure c
11e80 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a reated by the.**
11e90 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
11ea0 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ble()] interface
11eb0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c . A result tabl
11ec0 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a e records the.**
11ed0 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 complete query
11ee0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 results from one
11ef0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 or more queries
11f00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c ..**.** The tabl
11f10 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 e conceptually h
11f20 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 as a number of r
11f30 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e ows and columns.
11f40 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e But.** these n
11f50 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 umbers are not p
11f60 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c art of the resul
11f70 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 t table itself.
11f80 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 These.** number
11f90 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 s are obtained s
11fa0 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 eparately. Let
11fb0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 N be the number
11fc0 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d of rows.** and M
11fd0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
11fe0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a f columns..**.**
11ff0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
12000 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
12010 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d ointers to zero-
12020 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
12030 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 strings..** The
12040 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 re are (N+1)*M e
12050 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 lements in the a
12060 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 rray. The first
12070 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e M pointers poin
12080 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 t.** to zero-ter
12090 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
120a0 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 that contain th
120b0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 e names of the c
120c0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 olumns..** The r
120d0 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 emaining entries
120e0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 all point to qu
120f0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 ery results. NU
12100 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 LL values result
12110 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e .** in NULL poin
12120 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 ters. All other
12130 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 values are in t
12140 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d heir UTF-8 zero-
12150 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
12160 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 ring representat
12170 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 ion as returned
12180 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by [sqlite3_colu
12190 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a mn_text()]..**.*
121a0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
121b0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f might consist o
121c0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 f one or more me
121d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
121e0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 ..** It is not s
121f0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 afe to pass a re
12200 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 sult table direc
12210 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f tly to [sqlite3_
12220 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 free()]..** A re
12230 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c sult table shoul
12240 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 d be deallocated
12250 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
12260 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a free_table()]..*
12270 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 *.** As an examp
12280 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 le of the result
12290 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 table format, s
122a0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 uppose a query r
122b0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 esult.** is as f
122c0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
122d0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
122e0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 ** Name
122f0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 | Age.**
12300 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------
12310 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a -------------.**
12320 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 Alice
12330 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 | 43.**
12340 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c Bob |
12350 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 28.** Ci
12360 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a ndy | 21.*
12370 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
12380 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 uote>.**.** Ther
12390 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e e are two column
123a0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 (M==2) and thre
123b0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 e rows (N==3).
123c0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 Thus the.** resu
123d0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 lt table has 8 e
123e0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 ntries. Suppose
123f0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
12400 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 e is stored.** i
12410 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 n an array names
12420 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e azResult. Then
12430 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 azResult holds
12440 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a this content:.**
12450 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
12460 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
12470 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 azResult[0]
12480 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 = "Name";.**
12490 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
124a0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 ;1] = "Age";.**
124b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
124c0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 #91;2] = "Alice"
124d0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
124e0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 sult[3] = "4
124f0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 3";.** az
12500 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 Result[4] =
12510 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "Bob";.**
12520 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d azResult[5]
12530 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 = "28";.**
12540 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
12550 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 6] = "Cindy";.**
12560 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
12570 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a [7] = "21";.
12580 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
12590 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
125a0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
125b0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 le() function ev
125c0 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d aluates one or m
125d0 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e ore.** semicolon
125e0 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 -separated SQL s
125f0 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 tatements in the
12600 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
12610 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 UTF-8.** string
12620 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 of its 2nd para
12630 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 meter. It retur
12640 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c ns a result tabl
12650 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e e to the.** poin
12660 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 ter given in its
12670 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 3rd parameter..
12680 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 **.** After the
12690 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e calling function
126a0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 has finished us
126b0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 ing the result,
126c0 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 it should.** pas
126d0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f s the pointer to
126e0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
126f0 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 e to sqlite3_fre
12700 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 e_table() in ord
12710 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 er to.** release
12720 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 the memory that
12730 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 was malloced.
12740 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 Because of the w
12750 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ay the.** [sqlit
12760 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 e3_malloc()] hap
12770 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 pens within sqli
12780 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c te3_get_table(),
12790 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 the calling.**
127a0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f function must no
127b0 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 t try to call [s
127c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 qlite3_free()] d
127d0 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a irectly. Only.*
127e0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f * [sqlite3_free_
127f0 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 table()] is able
12800 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 to release the
12810 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 memory properly
12820 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a and safely..**.*
12830 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
12840 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 t_table() interf
12850 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 ace is implement
12860 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 ed as a wrapper
12870 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 around.** [sqlit
12880 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 e3_exec()]. The
12890 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
128a0 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 le() routine doe
128b0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 s not have acces
128c0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 s.** to any inte
128d0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 rnal data struct
128e0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ures of SQLite.
128f0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 It uses only th
12900 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 e public.** inte
12910 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 rface defined he
12920 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 re. As a conseq
12930 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 uence, errors th
12940 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a at occur in the.
12950 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 ** wrapper layer
12960 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 outside of the
12970 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 internal [sqlite
12980 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 3_exec()] call a
12990 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 re not.** reflec
129a0 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e ted in subsequen
129b0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 t calls to [sqli
129c0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f te3_errcode()] o
129d0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r [sqlite3_errms
129e0 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 g()]..**.** Requ
129f0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
12a00 32 33 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 2371] [H12373] [
12a10 48 31 32 33 37 34 5d 20 5b 48 31 32 33 37 36 5d H12374] [H12376]
12a20 20 5b 48 31 32 33 37 39 5d 20 5b 48 31 32 33 38 [H12379] [H1238
12a30 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 2].*/.SQLITE_API
12a40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 int sqlite3_get
12a50 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 _table(. sqlite
12a60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
12a70 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
12a80 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
12a90 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f har *zSql, /
12aa0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c * SQL to be eval
12ab0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 uated */. char
12ac0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 ***pazResult,
12ad0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 /* Results of t
12ae0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e he query */. in
12af0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 t *pnRow,
12b00 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
12b10 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 result rows wri
12b20 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 tten here */. i
12b30 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 nt *pnColumn,
12b40 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
12b50 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 f result columns
12b60 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
12b70 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d . char **pzErrm
12b80 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f sg /* Erro
12b90 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
12ba0 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f re */.);.SQLITE_
12bb0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
12bc0 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 _free_table(char
12bd0 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a **result);../*.
12be0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 ** CAPI3REF: For
12bf0 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 matted String Pr
12c00 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 inting Functions
12c10 20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30 30 {H17400} <S7000
12c20 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 0><S20000>.**.**
12c30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
12c40 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 are work-alikes
12c50 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 of the "printf()
12c60 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 " family of func
12c70 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 tions.** from th
12c80 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
12c90 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rary..**.** The
12ca0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
12cb0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d ) and sqlite3_vm
12cc0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
12cd0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a s write their.**
12ce0 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 results into me
12cf0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
12d00 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
12d10 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 oc()]..** The st
12d20 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
12d30 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 y these two rout
12d40 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a ines should be.*
12d50 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 * released by [s
12d60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 qlite3_free()].
12d70 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 Both routines r
12d80 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 eturn a.** NULL
12d90 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 pointer if [sqli
12da0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 te3_malloc()] is
12db0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
12dc0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 ate enough.** me
12dd0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
12de0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e resulting strin
12df0 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 g..**.** In sqli
12e00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 te3_snprintf() r
12e10 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 outine is simila
12e20 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 r to "snprintf()
12e30 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 " from.** the st
12e40 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
12e50 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 . The result is
12e60 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
12e70 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 e.** buffer supp
12e80 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f lied as the seco
12e90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f nd parameter who
12ea0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e se size is given
12eb0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 by.** the first
12ec0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 parameter. Note
12ed0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 that the order
12ee0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 of the.** first
12ef0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 two parameters i
12f00 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 s reversed from
12f10 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 snprintf(). Thi
12f20 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f s is an.** histo
12f30 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 rical accident t
12f40 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 hat cannot be fi
12f50 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 xed without brea
12f60 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 king.** backward
12f70 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
12f80 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 Note also that
12f90 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
12fa0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 f().** returns a
12fb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 pointer to its
12fc0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f buffer instead o
12fd0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a f the number of.
12fe0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 ** characters ac
12ff0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 tually written i
13000 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 nto the buffer.
13010 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a We admit that.*
13020 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
13030 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 characters writt
13040 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f en would be a mo
13050 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e re useful return
13060 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 .** value but we
13070 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 cannot change t
13080 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
13090 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 n of sqlite3_snp
130a0 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 rintf().** now w
130b0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 ithout breaking
130c0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
130d0 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 *.** As long as
130e0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 the buffer size
130f0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 is greater than
13100 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e zero, sqlite3_sn
13110 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 printf().** guar
13120 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
13130 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 buffer is always
13140 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
13150 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 . The first.**
13160 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 parameter "n" is
13170 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 the total size
13180 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 of the buffer, i
13190 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 ncluding space f
131a0 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 or.** the zero t
131b0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 erminator. So t
131c0 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e he longest strin
131d0 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f g that can be co
131e0 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 mpletely.** writ
131f0 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 ten will be n-1
13200 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
13210 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
13220 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 all implement s
13230 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 ome additional f
13240 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 ormatting.** opt
13250 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 ions that are us
13260 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 eful for constru
13270 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d cting SQL statem
13280 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 ents..** All of
13290 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 the usual printf
132a0 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 () formatting op
132b0 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e tions apply. In
132c0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 addition, there
132d0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c .** is are "%q",
132e0 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 "%Q", and "%z"
132f0 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 options..**.** T
13300 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 he %q option wor
13310 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 ks like %s in th
13320 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 at it substitute
13330 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 s a null-termina
13340 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 ted.** string fr
13350 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 om the argument
13360 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c list. But %q al
13370 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 so doubles every
13380 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e '\'' character.
13390 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e .** %q is design
133a0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 ed for use insid
133b0 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 e a string liter
133c0 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 al. By doubling
133d0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 each '\''.** ch
133e0 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 aracter it escap
133f0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 es that characte
13400 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 r and allows it
13410 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 to be inserted i
13420 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e nto.** the strin
13430 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 g..**.** For exa
13440 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 mple, assume the
13450 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 string variable
13460 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 zText contains
13470 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a text as follows:
13480 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
13490 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
134a0 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 r *zText = "It's
134b0 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a a happy day!";.
134c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
134d0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 quote>.**.** One
134e0 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 can use this te
134f0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 xt in an SQL sta
13500 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 tement as follow
13510 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
13520 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
13530 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
13540 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
13550 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
13560 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 ALUES('%q')", zT
13570 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
13580 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
13590 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
135a0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
135b0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
135c0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
135d0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 Because the %q f
135e0 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 ormat string is
135f0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 used, the '\'' c
13600 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 haracter in zTex
13610 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 t.** is escaped
13620 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 and the SQL gene
13630 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c rated is as foll
13640 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
13650 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
13660 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
13670 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 le1 VALUES('It''
13680 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
13690 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
136a0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
136b0 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 is is correct.
136c0 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 Had we used %s i
136d0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 nstead of %q, th
136e0 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a e generated SQL.
136f0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f ** would have lo
13700 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a oked like this:.
13710 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
13720 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
13730 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
13740 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 ALUES('It's a ha
13750 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c ppy day!');.** <
13760 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
13770 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 e>.**.** This se
13780 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 cond example is
13790 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 an SQL syntax er
137a0 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 ror. As a gener
137b0 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 al rule you shou
137c0 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 ld.** always use
137d0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %q instead of %
137e0 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 s when inserting
137f0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 text into a str
13800 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a ing literal..**.
13810 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e ** The %Q option
13820 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 works like %q e
13830 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 xcept it also ad
13840 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 ds single quotes
13850 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f around.** the o
13860 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f utside of the to
13870 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 tal string. Add
13880 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 itionally, if th
13890 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 e parameter in t
138a0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c he.** argument l
138b0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ist is a NULL po
138c0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 inter, %Q substi
138d0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 tutes the text "
138e0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a NULL" (without.*
138f0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 * single quotes)
13900 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 in place of the
13910 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c %Q option. So,
13920 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e for example, on
13930 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a e could say:.**.
13940 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
13950 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
13960 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
13970 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
13980 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
13990 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a %Q)", zText);.**
139a0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 sqlite3_exec(d
139b0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 b, zSQL, 0, 0, 0
139c0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 );.** sqlite3_f
139d0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f ree(zSQL);.** </
139e0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
139f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 >.**.** The code
13a00 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 above will rend
13a10 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c er a correct SQL
13a20 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
13a30 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 e zSQL.** variab
13a40 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a le even if the z
13a50 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 Text variable is
13a60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
13a70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 .**.** The "%z"
13a80 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
13a90 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 n works exactly
13aa0 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 like "%s" with t
13ab0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 he.** addition t
13ac0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 hat after the st
13ad0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 ring has been re
13ae0 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e ad and copied in
13af0 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 to.** the result
13b00 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
13b10 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 )] is called on
13b20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
13b30 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 52 65 . {END}.**.** Re
13b40 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
13b50 48 31 37 34 30 33 5d 20 5b 48 31 37 34 30 36 5d H17403] [H17406]
13b60 20 5b 48 31 37 34 30 37 5d 0a 2a 2f 0a 53 51 4c [H17407].*/.SQL
13b70 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 ITE_API char *sq
13b80 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f lite3_mprintf(co
13b90 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a nst char*,...);.
13ba0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 SQLITE_API char
13bb0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 *sqlite3_vmprint
13bc0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 f(const char*, v
13bd0 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f a_list);.SQLITE_
13be0 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 API char *sqlite
13bf0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 3_snprintf(int,c
13c00 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
13c10 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
13c20 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
13c30 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 Allocation Subsy
13c40 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 stem {H17300} <S
13c50 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20000>.**.** The
13c60 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 SQLite core us
13c70 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 es these three r
13c80 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 outines for all
13c90 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e of its own.** in
13ca0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c ternal memory al
13cb0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 location needs.
13cc0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 "Core" in the pr
13cd0 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a evious sentence.
13ce0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c ** does not incl
13cf0 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 ude operating-sy
13d00 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 stem specific VF
13d10 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
13d20 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 . The.** Window
13d30 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 s VFS uses nativ
13d40 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 e malloc() and f
13d50 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f ree() for some o
13d60 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a perations..**.**
13d70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c The sqlite3_mal
13d80 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 loc() routine re
13d90 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
13da0 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 to a block.** of
13db0 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 memory at least
13dc0 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 N bytes in leng
13dd0 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 th, where N is t
13de0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
13df0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c If sqlite3_mall
13e00 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 oc() is unable t
13e10 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 o obtain suffici
13e20 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f ent free.** memo
13e30 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 ry, it returns a
13e40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
13e50 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 If the parameter
13e60 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 N to.** sqlite3
13e70 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 _malloc() is zer
13e80 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 o or negative th
13e90 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f en sqlite3_mallo
13ea0 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 c() returns.** a
13eb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
13ec0 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c *.** Calling sql
13ed0 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 ite3_free() with
13ee0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 a pointer previ
13ef0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a ously returned.*
13f00 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c * by sqlite3_mal
13f10 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 loc() or sqlite3
13f20 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 _realloc() relea
13f30 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 ses that memory
13f40 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 so.** that it mi
13f50 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 ght be reused.
13f60 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 The sqlite3_free
13f70 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a () routine is.**
13f80 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 a no-op if is c
13f90 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c alled with a NUL
13fa0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 L pointer. Pass
13fb0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ing a NULL point
13fc0 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 er.** to sqlite3
13fd0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c _free() is harml
13fe0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e ess. After bein
13ff0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a g freed, memory.
14000 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 ** should neithe
14010 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 r be read nor wr
14020 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 itten. Even rea
14030 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 ding previously
14040 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 freed.** memory
14050 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 might result in
14060 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 a segmentation f
14070 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 ault or other se
14080 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d vere error..** M
14090 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e emory corruption
140a0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e , a segmentation
140b0 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 fault, or other
140c0 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a severe error.**
140d0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 might result if
140e0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
140f0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
14100 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
14110 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f r that.** was no
14120 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 t obtained from
14130 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14140 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c or sqlite3_real
14150 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 loc()..**.** The
14160 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
14170 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
14180 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 empts to resize
14190 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 a.** prior memor
141a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
141b0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 be at least N by
141c0 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 tes, where N is
141d0 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 the.** second pa
141e0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 rameter. The me
141f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
14200 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 to be resized is
14210 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 the first.** pa
14220 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 rameter. If the
14230 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
14240 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
14250 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 loc().** is a NU
14260 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
14270 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 its behavior is
14280 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c identical to cal
14290 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
142a0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 malloc(N) where
142b0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
142c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
142d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
142e0 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 ** If the second
142f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
14300 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
14310 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 is zero or.** ne
14320 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 gative then the
14330 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 behavior is exac
14340 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 tly the same as
14350 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 calling.** sqlit
14360 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 e3_free(P) where
14370 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 P is the first
14380 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
14390 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
143a0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c ** sqlite3_reall
143b0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 oc() returns a p
143c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f ointer to a memo
143d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
143e0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 of at least N b
143f0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 ytes in size or
14400 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 NULL if sufficie
14410 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 nt memory is una
14420 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 vailable..** If
14430 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 M is the size of
14440 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
14450 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 ation, then min(
14460 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 N,M) bytes.** of
14470 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
14480 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 ation are copied
14490 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e into the beginn
144a0 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 ing of buffer re
144b0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
144c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 ite3_realloc() a
144d0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c nd the prior all
144e0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 ocation is freed
144f0 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f ..** If sqlite3_
14500 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e realloc() return
14510 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 s NULL, then the
14520 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
14530 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 n.** is not free
14540 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d d..**.** The mem
14550 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 ory returned by
14560 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14570 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 and sqlite3_rea
14580 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 lloc().** is alw
14590 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 ays aligned to a
145a0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 t least an 8 byt
145b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 e boundary. {END
145c0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 }.**.** The defa
145d0 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ult implementati
145e0 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 on of the memory
145f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
14600 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 ystem uses.** th
14610 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c e malloc(), real
14620 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
14630 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 provided by the
14640 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
14650 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d ary..** {H17382}
14660 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c However, if SQL
14670 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
14680 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 with the.** SQLI
14690 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c TE_MEMORY_SIZE=<
146a0 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 i>NNN</i> C prep
146b0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 rocessor macro (
146c0 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e where <i>NNN</i>
146d0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 .** is an intege
146e0 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 r), then SQLite
146f0 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63 20 create a static
14700 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 array of at leas
14710 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 t.** <i>NNN</i>
14720 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
14730 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72 61 d uses that arra
14740 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 y for all of its
14750 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f dynamic.** memo
14760 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
14770 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 eds. {END} Addi
14780 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c tional memory al
14790 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a locator options.
147a0 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ** may be added
147b0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
147c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c es..**.** In SQL
147d0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
147e0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 0 and 3.5.1, it
147f0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 was possible to
14800 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 define.** the SQ
14810 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 LITE_OMIT_MEMORY
14820 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 _ALLOCATION whic
14830 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 h would cause th
14840 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d e built-in.** im
14850 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
14860 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 these routines t
14870 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 o be omitted. T
14880 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a hat capability.*
14890 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 * is no longer p
148a0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 rovided. Only b
148b0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
148c0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 llocators can be
148d0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 used..**.** The
148e0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 Windows OS inte
148f0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c rface layer call
14900 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 s.** the system
14910 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 malloc() and fre
14920 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 e() directly whe
14930 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 n converting.**
14940 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 filenames betwee
14950 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f n the UTF-8 enco
14960 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c ding used by SQL
14970 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 ite.** and whate
14980 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 ver filename enc
14990 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 oding is used by
149a0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 the particular
149b0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 Windows.** insta
149c0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 llation. Memory
149d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
149e0 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c rs are detected,
149f0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 but.** they are
14a00 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 reported back a
14a10 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 s [SQLITE_CANTOP
14a20 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 EN] or.** [SQLIT
14a30 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 E_IOERR] rather
14a40 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d than [SQLITE_NOM
14a50 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 EM]..**.** Requi
14a60 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 rements:.** [H17
14a70 33 30 33 5d 20 5b 48 31 37 33 30 34 5d 20 5b 48 303] [H17304] [H
14a80 31 37 33 30 35 5d 20 5b 48 31 37 33 30 36 5d 20 17305] [H17306]
14a90 5b 48 31 37 33 31 30 5d 20 5b 48 31 37 33 31 32 [H17310] [H17312
14aa0 5d 20 5b 48 31 37 33 31 35 5d 20 5b 48 31 37 33 ] [H17315] [H173
14ab0 31 38 5d 0a 2a 2a 20 5b 48 31 37 33 32 31 5d 20 18].** [H17321]
14ac0 5b 48 31 37 33 32 32 5d 20 5b 48 31 37 33 32 33 [H17322] [H17323
14ad0 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e ].**.** The poin
14ae0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ter arguments to
14af0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
14b00 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
14b10 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 ealloc()].** mus
14b20 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c t be either NULL
14b30 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 or else pointer
14b40 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 s obtained from
14b50 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 a prior.** invoc
14b60 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
14b70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 3_malloc()] or [
14b80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
14b90 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 )] that have.**
14ba0 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c not yet been rel
14bb0 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eased..**.** The
14bc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
14bd0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 t not read or wr
14be0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a ite any part of.
14bf0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 ** a block of me
14c00 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 mory after it ha
14c10 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 s been released
14c20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
14c30 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 3_free()] or [sq
14c40 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
14c50 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
14c60 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 void *sqlite3_ma
14c70 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 lloc(int);.SQLIT
14c80 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 E_API void *sqli
14c90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 te3_realloc(void
14ca0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
14cb0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
14cc0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f _free(void*);../
14cd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
14ce0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 emory Allocator
14cf0 53 74 61 74 69 73 74 69 63 73 20 7b 48 31 37 33 Statistics {H173
14d00 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 70} <S30210>.**.
14d10 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 ** SQLite provid
14d20 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 es these two int
14d30 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f erfaces for repo
14d40 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 rting on the sta
14d50 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 tus.** of the [s
14d60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
14d70 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
14d80 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
14d90 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 _realloc()].** r
14da0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 outines, which f
14db0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e orm the built-in
14dc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14dd0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a on subsystem..**
14de0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
14df0 3a 0a 2a 2a 20 5b 48 31 37 33 37 31 5d 20 5b 48 :.** [H17371] [H
14e00 31 37 33 37 33 5d 20 5b 48 31 37 33 37 34 5d 20 17373] [H17374]
14e10 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a 53 51 4c 49 [H17375].*/.SQLI
14e20 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 TE_API sqlite3_i
14e30 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d nt64 sqlite3_mem
14e40 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a ory_used(void);.
14e50 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
14e60 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
14e70 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
14e80 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 r(int resetFlag)
14e90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
14ea0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d F: Pseudo-Random
14eb0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f Number Generato
14ec0 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30 r {H17390} <S200
14ed0 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 00>.**.** SQLite
14ee0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 contains a high
14ef0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d -quality pseudo-
14f00 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 random number ge
14f10 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 nerator (PRNG) u
14f20 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 sed to.** select
14f30 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c random [ROWID |
14f40 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e ROWIDs] when in
14f50 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f serting new reco
14f60 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 rds into a table
14f70 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 that.** already
14f80 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 uses the larges
14f90 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 t possible [ROWI
14fa0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 D]. The PRNG is
14fb0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a also used for.*
14fc0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 * the build-in r
14fd0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 andom() and rand
14fe0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e omblob() SQL fun
14ff0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e ctions. This in
15000 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a terface allows.*
15010 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * applications t
15020 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d o access the sam
15030 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 e PRNG for other
15040 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a purposes..**.**
15050 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 A call to this
15060 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e routine stores N
15070 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d bytes of random
15080 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 ness into buffer
15090 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 P..**.** The fi
150a0 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f rst time this ro
150b0 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 utine is invoked
150c0 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 (either interna
150d0 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 lly or by.** the
150e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 application) th
150f0 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 e PRNG is seeded
15100 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 using randomnes
15110 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 s obtained.** fr
15120 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 om the xRandomne
15130 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 ss method of the
15140 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
15150 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 3_vfs] object..*
15160 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 * On all subsequ
15170 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c ent invocations,
15180 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 the pseudo-rand
15190 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 omness is genera
151a0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c ted.** internall
151b0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 y and without re
151c0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 course to the [s
151d0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e qlite3_vfs] xRan
151e0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f domness.** metho
151f0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 d..**.** Require
15200 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 ments:.** [H1739
15210 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 2].*/.SQLITE_API
15220 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 void sqlite3_ra
15230 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 ndomness(int N,
15240 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a void *P);../*.**
15250 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
15260 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a le-Time Authoriz
15270 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 ation Callbacks
15280 7b 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 {H12500} <S70100
15290 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
152a0 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 tine registers a
152b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
152c0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 back with a part
152d0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
152e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c ase connection],
152f0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 supplied in the
15300 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
15310 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a .** The authoriz
15320 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
15330 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 nvoked as SQL st
15340 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 atements are bei
15350 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 ng compiled.** b
15360 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
15370 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
15380 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 iants [sqlite3_p
15390 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a repare_v2()],.**
153a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
153b0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 e16()] and [sqli
153c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
153d0 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 ()]. At various
153e0 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e .** points durin
153f0 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f g the compilatio
15400 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f n process, as lo
15410 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 gic is being cre
15420 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f ated.** to perfo
15430 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f rm various actio
15440 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a ns, the authoriz
15450 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
15460 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 nvoked to.** see
15470 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e if those action
15480 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 s are allowed.
15490 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
154a0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a allback should.*
154b0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
154c0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 _OK] to allow th
154d0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 e action, [SQLIT
154e0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 E_IGNORE] to dis
154f0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 allow the.** spe
15500 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 cific action but
15510 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 allow the SQL s
15520 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 tatement to cont
15530 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f inue to be.** co
15540 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 mpiled, or [SQLI
15550 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 TE_DENY] to caus
15560 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c e the entire SQL
15570 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
15580 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 .** rejected wit
15590 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 h an error. If
155a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
155b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a allback returns.
155c0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 ** any value oth
155d0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
155e0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 IGNORE], [SQLITE
155f0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 _OK], or [SQLITE
15600 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 _DENY].** then t
15610 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 he [sqlite3_prep
15620 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 are_v2()] or equ
15630 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 ivalent call tha
15640 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 t triggered.** t
15650 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 he authorizer wi
15660 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 ll fail with an
15670 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a error message..*
15680 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 *.** When the ca
15690 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
156a0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 SQLITE_OK], that
156b0 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 means the opera
156c0 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 tion.** requeste
156d0 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 d is ok. When t
156e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
156f0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 rns [SQLITE_DENY
15700 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ], the.** [sqlit
15710 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
15720 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
15730 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
15740 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 ed the.** author
15750 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
15760 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
15770 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 sage explaining
15780 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 that.** access i
15790 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a s denied. .**.**
157a0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
157b0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
157c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
157d0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
157e0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
157f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
15800 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
15810 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54 r() interface. T
15820 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
15830 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ter.** to the ca
15840 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
15850 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 eger [SQLITE_COP
15860 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d Y | action code]
15870 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a that specifies.
15880 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 ** the particula
15890 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 r action to be a
158a0 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 uthorized. The t
158b0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 hird through six
158c0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a th parameters.**
158d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
158e0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e are zero-termin
158f0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 ated strings tha
15900 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 t contain additi
15910 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 onal.** details
15920 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e about the action
15930 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 to be authorize
15940 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 d..**.** If the
15950 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b action code is [
15960 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 SQLITE_READ].**
15970 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
15980 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
15990 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
159a0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
159b0 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d tatement] statem
159c0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 ent is construct
159d0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 ed to substitute
159e0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 .** a NULL value
159f0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 in place of the
15a00 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
15a10 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a at would have.**
15a20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 been read if [S
15a30 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 QLITE_OK] had be
15a40 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 en returned. Th
15a50 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 e [SQLITE_IGNORE
15a60 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 ].** return can
15a70 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 be used to deny
15a80 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 an untrusted use
15a90 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 r access to indi
15aa0 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e vidual.** column
15ab0 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a s of a table..**
15ac0 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 If the action c
15ad0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 ode is [SQLITE_D
15ae0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 ELETE] and the c
15af0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a allback returns.
15b00 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ** [SQLITE_IGNOR
15b10 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c E] then the [DEL
15b20 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 ETE] operation p
15b30 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a roceeds but the.
15b40 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 ** [truncate opt
15b50 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 imization] is di
15b60 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 sabled and all r
15b70 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 ows are deleted
15b80 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a individually..**
15b90 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 .** An authorize
15ba0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b r is used when [
15bb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 sqlite3_prepare
15bc0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 | preparing].**
15bd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 SQL statements f
15be0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 rom an untrusted
15bf0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 source, to ensu
15c00 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 re that the SQL
15c10 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f statements.** do
15c20 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 not try to acce
15c30 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 ss data they are
15c40 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 not allowed to
15c50 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 see, or that the
15c60 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 y do not.** try
15c70 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 to execute malic
15c80 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 ious statements
15c90 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 that damage the
15ca0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a database. For.*
15cb0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 * example, an ap
15cc0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c plication may al
15cd0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e low a user to en
15ce0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a ter arbitrary.**
15cf0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 SQL queries for
15d00 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 evaluation by a
15d10 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 database. But
15d20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
15d30 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 does.** not want
15d40 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 the user to be
15d50 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 able to make arb
15d60 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 itrary changes t
15d70 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 o the.** databas
15d80 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 e. An authorize
15d90 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 r could then be
15da0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 put in place whi
15db0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 le the.** user-e
15dc0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 ntered SQL is be
15dd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
15de0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d pare | prepared]
15df0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f that.** disallo
15e00 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 ws everything ex
15e10 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 cept [SELECT] st
15e20 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
15e30 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
15e40 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 t need to proces
15e50 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 s SQL from untru
15e60 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 sted sources.**
15e70 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 might also consi
15e80 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 der lowering res
15e90 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 ource limits usi
15ea0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 ng [sqlite3_limi
15eb0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 t()].** and limi
15ec0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 ting database si
15ed0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 ze using the [ma
15ee0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
15ef0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 RAGMA].** in add
15f00 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 ition to using a
15f10 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a n authorizer..**
15f20 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c .** Only a singl
15f30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e e authorizer can
15f40 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 be in place on
15f50 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
15f60 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 ction.** at a ti
15f70 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 me. Each call t
15f80 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 o sqlite3_set_au
15f90 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 thorizer overrid
15fa0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f es the.** previo
15fb0 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c us call. Disabl
15fc0 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 e the authorizer
15fd0 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 by installing a
15fe0 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a NULL callback..
15ff0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ** The authorize
16000 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 r is disabled by
16010 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 default..**.**
16020 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
16030 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 allback must not
16040 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
16050 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
16060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
16070 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
16080 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 voked the author
16090 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a izer callback..*
160a0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c * Note that [sql
160b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
160c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
160d0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 step()] both mod
160e0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 ify their.** dat
160f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
16100 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e s for the meanin
16110 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e g of "modify" in
16120 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e this paragraph.
16130 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c .**.** When [sql
16140 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
16150 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 )] is used to pr
16160 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
16170 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d t, the.** statem
16180 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d ent might be re-
16190 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 prepared during
161a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
161b0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 due to a .** sc
161c0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 hema change. He
161d0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 nce, the applica
161e0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 tion should ensu
161f0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 re that the.** c
16200 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 orrect authorize
16210 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 r callback remai
16220 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 ns in place duri
16230 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ng the [sqlite3_
16240 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e step()]..**.** N
16250 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 ote that the aut
16260 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
16270 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 is invoked only
16280 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 during.** [sqli
16290 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
162a0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 r its variants.
162b0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 Authorization i
162c0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d s not.** perform
162d0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d ed during statem
162e0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 ent evaluation i
162f0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 n [sqlite3_step(
16300 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 )], unless.** as
16310 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 stated in the p
16320 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
16330 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 h, sqlite3_step(
16340 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c ) invokes.** sql
16350 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
16360 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 ) to reprepare a
16370 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
16380 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
16390 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
163a0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 30 31 ents:.** [H12501
163b0 5d 20 5b 48 31 32 35 30 32 5d 20 5b 48 31 32 35 ] [H12502] [H125
163c0 30 33 5d 20 5b 48 31 32 35 30 34 5d 20 5b 48 31 03] [H12504] [H1
163d0 32 35 30 35 5d 20 5b 48 31 32 35 30 36 5d 20 5b 2505] [H12506] [
163e0 48 31 32 35 30 37 5d 20 5b 48 31 32 35 31 30 5d H12507] [H12510]
163f0 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 20 5b 48 31 .** [H12511] [H1
16400 32 35 31 32 5d 20 5b 48 31 32 35 32 30 5d 20 5b 2512] [H12520] [
16410 48 31 32 35 32 31 5d 20 5b 48 31 32 35 32 32 5d H12521] [H12522]
16420 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
16430 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 nt sqlite3_set_a
16440 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c uthorizer(. sql
16450 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 ite3*,. int (*x
16460 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c Auth)(void*,int,
16470 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
16480 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
16490 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 ar*,const char*)
164a0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 ,. void *pUserD
164b0 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ata.);../*.** CA
164c0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
164d0 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 er Return Codes
164e0 7b 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 {H12590} <H12500
164f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c >.**.** The [sql
16500 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
16510 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
16520 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
16530 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 on] must.** retu
16540 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 rn either [SQLIT
16550 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 E_OK] or one of
16560 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 these two consta
16570 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 nts in order.**
16580 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 to signal SQLite
16590 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
165a0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 the action is pe
165b0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 rmitted. See th
165c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 e.** [sqlite3_se
165d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
165e0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 uthorizer docume
165f0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 ntation] for add
16600 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
16610 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 mation..*/.#defi
16620 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 ne SQLITE_DENY
16630 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 1 /* Abort th
16640 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
16650 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f with an error */
16660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16670 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f IGNORE 2 /* Do
16680 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 n't allow access
16690 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 , but don't gene
166a0 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f rate an error */
166b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
166c0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 : Authorizer Act
166d0 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 ion Codes {H1255
166e0 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 0} <H12500>.**.*
166f0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 * The [sqlite3_s
16700 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d et_authorizer()]
16710 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
16720 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 ters a callback
16730 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 function.** that
16740 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 is invoked to a
16750 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e uthorize certain
16760 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
16770 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 ctions. The.**
16780 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
16790 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
167a0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 is an integer c
167b0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 ode that specifi
167c0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f es.** what actio
167d0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f n is being autho
167e0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 rized. These ar
167f0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 e the integer ac
16800 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a tion codes that.
16810 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
16820 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 r callback may b
16830 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 e passed..**.**
16840 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 These action cod
16850 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 e values signify
16860 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 what kind of op
16870 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 eration is to be
16880 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 .** authorized.
16890 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 The 3rd and 4th
168a0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
168b0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e he authorization
168c0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e .** callback fun
168d0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 ction will be pa
168e0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c rameters or NULL
168f0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 depending on wh
16900 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ich of these.**
16910 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 codes is used as
16920 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
16930 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 meter. The 5th
16940 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
16950 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 .** authorizer c
16960 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
16970 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
16980 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 ase ("main", "te
16990 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 mp",.** etc.) if
169a0 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 applicable. Th
169b0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 6th parameter
169c0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
169d0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 r callback.** is
169e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
169f0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 inner-most trig
16a00 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 ger or view that
16a10 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
16a20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 for.** the acces
16a30 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c s attempt or NUL
16a40 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 L if this access
16a50 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 attempt is dire
16a60 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 ctly from.** top
16a70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e -level SQL code.
16a80 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
16a90 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 35 31 5d nts:.** [H12551]
16aa0 20 5b 48 31 32 35 35 32 5d 20 5b 48 31 32 35 35 [H12552] [H1255
16ab0 33 5d 20 5b 48 31 32 35 35 34 5d 0a 2a 2f 0a 2f 3] [H12554].*/./
16ac0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
16ad0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
16ae0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 *********** 3rd
16af0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 ************ 4th
16b00 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 ***********/.#d
16b10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
16b20 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ATE_INDEX
16b30 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 1 /* Index
16b40 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
16b50 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
16b60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
16b70 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 TE_TABLE
16b80 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 2 /* Table N
16b90 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
16ba0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
16bb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
16bc0 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 E_TEMP_INDEX
16bd0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 3 /* Index Na
16be0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
16bf0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
16c00 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
16c10 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
16c20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 4 /* Table Nam
16c30 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
16c40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
16c50 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
16c60 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 TEMP_TRIGGER 5
16c70 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
16c80 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
16c90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
16ca0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
16cb0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 EMP_VIEW 6
16cc0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
16cd0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
16ce0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
16cf0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 SQLITE_CREATE_TR
16d00 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 IGGER 7
16d10 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
16d20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
16d30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
16d40 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 QLITE_CREATE_VIE
16d50 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 W 8
16d60 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
16d70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
16d80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
16d90 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 LITE_DELETE
16da0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 9 /
16db0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
16dc0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
16dd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
16de0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 ITE_DROP_INDEX
16df0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 10 /*
16e00 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
16e10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
16e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16e30 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 TE_DROP_TABLE
16e40 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 11 /*
16e50 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
16e60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
16e70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16e80 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 E_DROP_TEMP_INDE
16e90 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 X 12 /* I
16ea0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
16eb0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
16ec0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16ed0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 _DROP_TEMP_TABLE
16ee0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 13 /* Ta
16ef0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
16f00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
16f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16f20 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 DROP_TEMP_TRIGGE
16f30 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 R 14 /* Tri
16f40 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
16f50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
16f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
16f70 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 ROP_TEMP_VIEW
16f80 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 15 /* View
16f90 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
16fa0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
16fb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
16fc0 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 OP_TRIGGER
16fd0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 16 /* Trigg
16fe0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
16ff0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
17000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
17010 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 P_VIEW
17020 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 17 /* View N
17030 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
17040 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
17050 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 fine SQLITE_INSE
17060 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 RT
17070 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 18 /* Table N
17080 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
17090 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
170a0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d ine SQLITE_PRAGM
170b0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 A
170c0 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 19 /* Pragma N
170d0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 ame 1st arg
170e0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 or NULL */.#defi
170f0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 ne SQLITE_READ
17100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
17110 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
17120 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 e Column Na
17130 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
17140 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 e SQLITE_SELECT
17150 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 21
17160 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
17170 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
17180 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
17190 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 SQLITE_TRANSACT
171a0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 ION 22
171b0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 /* Operation
171c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
171d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
171e0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 SQLITE_UPDATE
171f0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 23
17200 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
17210 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 Column Name
17220 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
17230 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 QLITE_ATTACH
17240 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 24
17250 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 /* Filename
17260 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
17270 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17280 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 LITE_DETACH
17290 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 25 /
172a0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 * Database Name
172b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
172c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
172d0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 ITE_ALTER_TABLE
172e0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 26 /*
172f0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
17300 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
17310 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17320 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 TE_REINDEX
17330 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 27 /*
17340 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
17350 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
17360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17370 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 E_ANALYZE
17380 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 28 /* T
17390 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
173a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
173b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
173c0 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 _CREATE_VTABLE
173d0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 29 /* Ta
173e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f ble Name Mo
173f0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f dule Name */
17400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17410 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 DROP_VTABLE
17420 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 30 /* Tab
17430 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
17440 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
17450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
17460 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 UNCTION
17470 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 31 /* NULL
17480 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 Func
17490 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 tion Name */.#
174a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 define SQLITE_SA
174b0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 VEPOINT
174c0 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 32 /* Opera
174d0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 tion Savep
174e0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 oint Name */.#d
174f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 efine SQLITE_COP
17500 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 Y
17510 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 0 /* No lon
17520 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a ger used */../*.
17530 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 ** CAPI3REF: Tra
17540 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 cing And Profili
17550 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 ng Functions {H1
17560 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2280} <S60400>.*
17570 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
17580 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
17590 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c nes register cal
175a0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 lback functions
175b0 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 that can be used
175c0 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 for.** tracing
175d0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 and profiling th
175e0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 e execution of S
175f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
17600 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 *.** The callbac
17610 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
17620 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
17630 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f _trace() is invo
17640 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 ked at.** variou
17650 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 s times when an
17660 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 SQL statement is
17670 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 being run by [s
17680 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
17690 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ** The callback
176a0 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 returns a UTF-8
176b0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
176c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
176d0 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 ext.** as the st
176e0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
176f0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 gins executing.
17700 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c Additional call
17710 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 backs occur.** a
17720 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 s each triggered
17730 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 subprogram is e
17740 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c ntered. The cal
17750 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 lbacks for trigg
17760 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 ers.** contain a
17770 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 UTF-8 SQL comme
17780 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 nt that identifi
17790 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a es the trigger..
177a0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 **.** The callba
177b0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
177c0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 stered by sqlite
177d0 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 3_profile() is i
177e0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 nvoked.** as eac
177f0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 h SQL statement
17800 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 finishes. The p
17810 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
17820 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
17830 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
17840 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 nt text and an e
17850 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d stimate of wall-
17860 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 clock time.** of
17870 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 how long that s
17880 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f tatement took to
17890 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 run..**.** Requ
178a0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
178b0 32 32 38 31 5d 20 5b 48 31 32 32 38 32 5d 20 5b 2281] [H12282] [
178c0 48 31 32 32 38 33 5d 20 5b 48 31 32 32 38 34 5d H12283] [H12284]
178d0 20 5b 48 31 32 32 38 35 5d 20 5b 48 31 32 32 38 [H12285] [H1228
178e0 37 5d 20 5b 48 31 32 32 38 38 5d 20 5b 48 31 32 7] [H12288] [H12
178f0 32 38 39 5d 0a 2a 2a 20 5b 48 31 32 32 39 30 5d 289].** [H12290]
17900 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 .*/.SQLITE_API S
17910 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
17920 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 AL void *sqlite3
17930 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c _trace(sqlite3*,
17940 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 void(*xTrace)(v
17950 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
17960 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 ), void*);.SQLIT
17970 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 E_API SQLITE_EXP
17980 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a ERIMENTAL void *
17990 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
179a0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 sqlite3*,. voi
179b0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 d(*xProfile)(voi
179c0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 d*,const char*,s
179d0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 qlite3_uint64),
179e0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
179f0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 API3REF: Query P
17a00 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b rogress Callback
17a10 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 s {H12910} <S604
17a20 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
17a30 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 outine configure
17a40 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e s a callback fun
17a50 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 ction - the.** p
17a60 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
17a70 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b - that is invok
17a80 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 ed periodically
17a90 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 during long.** r
17aa0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 unning calls to
17ab0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
17ac0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
17ad0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
17ae0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e e3_get_table()].
17af0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 An example use
17b00 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 for this.** int
17b10 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 erface is to kee
17b20 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 p a GUI updated
17b30 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 during a large q
17b40 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 uery..**.** If t
17b50 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
17b60 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
17b70 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 -zero, the opera
17b80 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 tion is.** inter
17b90 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 rupted. This fe
17ba0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 ature can be use
17bb0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
17bc0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 .** "Cancel" but
17bd0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f ton on a GUI pro
17be0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 gress dialog box
17bf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 ..**.** The prog
17c00 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 ress handler mus
17c10 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
17c20 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
17c30 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
17c40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
17c50 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 at invoked the p
17c60 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
17c70 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
17c80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
17c90 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
17ca0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
17cb0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
17cc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
17cd0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
17ce0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
17cf0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
17d00 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 h..**.** Require
17d10 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 31 ments:.** [H1291
17d20 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48 31 32 1] [H12912] [H12
17d30 39 31 33 5d 20 5b 48 31 32 39 31 34 5d 20 5b 48 913] [H12914] [H
17d40 31 32 39 31 35 5d 20 5b 48 31 32 39 31 36 5d 20 12915] [H12916]
17d50 5b 48 31 32 39 31 37 5d 20 5b 48 31 32 39 31 38 [H12917] [H12918
17d60 5d 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ].**.*/.SQLITE_A
17d70 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
17d80 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
17d90 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 (sqlite3*, int,
17da0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 int(*)(void*), v
17db0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
17dc0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 PI3REF: Opening
17dd0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 A New Database C
17de0 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 onnection {H1270
17df0 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S40200>.**.*
17e00 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
17e10 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 open an SQLite
17e20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 database file wh
17e30 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 ose name is give
17e40 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 n by the.** file
17e50 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 name argument. T
17e60 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
17e70 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 ment is interpre
17e80 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 ted as UTF-8 for
17e90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
17ea0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
17eb0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 pen_v2() and as
17ec0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
17ed0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 tive byte.** ord
17ee0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f er for sqlite3_o
17ef0 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 pen16(). A [data
17f00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
17f10 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c handle is usual
17f20 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 ly.** returned i
17f30 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 n *ppDb, even if
17f40 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
17f50 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 . The only exce
17f60 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a ption is that.**
17f70 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e if SQLite is un
17f80 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
17f90 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 memory to hold
17fa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
17fb0 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 ject,.** a NULL
17fc0 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 will be written
17fd0 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 into *ppDb inste
17fe0 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 ad of a pointer
17ff0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d to the [sqlite3]
18000 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 .** object. If t
18010 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
18020 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 pened (and/or cr
18030 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 eated) successfu
18040 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 lly, then.** [SQ
18050 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 LITE_OK] is retu
18060 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 rned. Otherwise
18070 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
18080 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 is returned. T
18090 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
180a0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c rrmsg()] or [sql
180b0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d ite3_errmsg16()]
180c0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 routines can be
180d0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a used to obtain.
180e0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 ** an English la
180f0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 nguage descripti
18100 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e on of the error.
18110 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 .**.** The defau
18120 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 lt encoding for
18130 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c the database wil
18140 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a l be UTF-8 if.**
18150 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
18160 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
18170 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 v2() is called a
18180 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 nd.** UTF-16 in
18190 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 the native byte
181a0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 order if sqlite3
181b0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 _open16() is use
181c0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 d..**.** Whether
181d0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 or not an error
181e0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 occurs when it
181f0 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 is opened, resou
18200 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 rces.** associat
18210 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
18220 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18230 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 ] handle should
18240 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a be released by.*
18250 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 * passing it to
18260 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
18270 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 ] when it is no
18280 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e longer required.
18290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
182a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 e3_open_v2() int
182b0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b erface works lik
182c0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 e sqlite3_open()
182d0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
182e0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 it accepts two a
182f0 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 dditional parame
18300 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f ters for additio
18310 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f nal control.** o
18320 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 ver the new data
18330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
18340 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 The flags para
18350 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f meter can take o
18360 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c ne of.** the fol
18370 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c lowing three val
18380 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 ues, optionally
18390 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 combined with th
183a0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 e .** [SQLITE_OP
183b0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 EN_NOMUTEX], [SQ
183c0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
183d0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 TEX], [SQLITE_OP
183e0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c EN_SHAREDCACHE],
183f0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 .** and/or [SQLI
18400 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
18410 41 43 48 45 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a ACHE] flags:.**.
18420 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b ** <dl>.** <dt>[
18430 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
18440 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ONLY]</dt>.** <d
18450 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
18460 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 s opened in read
18470 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 -only mode. If
18480 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 the database doe
18490 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 s not.** already
184a0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 exist, an error
184b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
184c0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 d>.**.** <dt>[SQ
184d0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
184e0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ITE]</dt>.** <dd
184f0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
18500 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
18510 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 ing and writing
18520 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 if possible, or
18530 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 reading.** only
18540 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 if the file is w
18550 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 rite protected b
18560 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 y the operating
18570 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 system. In eith
18580 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 er.** case the d
18590 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 atabase must alr
185a0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 eady exist, othe
185b0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 rwise an error i
185c0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e s returned.</dd>
185d0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 .**.** <dt>[SQLI
185e0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
185f0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 E] | [SQLITE_OPE
18600 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a N_CREATE]</dt>.*
18610 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
18620 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
18630 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
18640 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 ting, and is cre
18650 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 ates it if.** it
18660 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 does not alread
18670 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 y exist. This is
18680 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 the behavior th
18690 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 at is always use
186a0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 d for.** sqlite3
186b0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
186c0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 te3_open16().</d
186d0 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a d>.** </dl>.**.*
186e0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 * If the 3rd par
186f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
18700 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 3_open_v2() is n
18710 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a ot one of the.**
18720 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 combinations sh
18730 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 own above or one
18740 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 of the combinat
18750 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 ions shown above
18760 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 combined.** wit
18770 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 h the [SQLITE_OP
18780 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 EN_NOMUTEX], [SQ
18790 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
187a0 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 TEX],.** [SQLITE
187b0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
187c0 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 E] and/or [SQLIT
187d0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
187e0 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 HE] flags,.** th
187f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
18800 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
18810 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49 .** If the [SQLI
18820 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
18830 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 flag is set, th
18840 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
18850 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 connection.** op
18860 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 ens in the multi
18870 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
18880 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 ng mode] as long
18890 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 as the single-t
188a0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 hread.** mode ha
188b0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 s not been set a
188c0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
188d0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 49 r start-time. I
188e0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 f the.** [SQLITE
188f0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
18900 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 flag is set the
18910 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
18920 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a onnection opens.
18930 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c ** in the serial
18940 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
18950 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e mode] unless sin
18960 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a gle-thread was.*
18970 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c * previously sel
18980 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 ected at compile
18990 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
189a0 69 6d 65 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ime..** The [SQL
189b0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
189c0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 ACHE] flag cause
189d0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
189e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a onnection to be.
189f0 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 ** eligible to u
18a00 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 se [shared cache
18a10 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 mode], regardle
18a20 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
18a30 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 not shared.** c
18a40 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 ache is enabled
18a50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 using [sqlite3_e
18a60 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 nable_shared_cac
18a70 68 65 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b he()]. The.** [
18a80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
18a90 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 ATECACHE] flag c
18aa0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
18ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
18ac0 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 not.** particip
18ad0 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 ate in [shared c
18ae0 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 ache mode] even
18af0 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 if it is enabled
18b00 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 ..**.** If the f
18b10 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d ilename is ":mem
18b20 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 ory:", then a pr
18b30 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
18b40 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
18b50 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 ase.** is create
18b60 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 d for the connec
18b70 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d tion. This in-m
18b80 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 emory database w
18b90 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a ill vanish when.
18ba0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
18bb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
18bc0 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 osed. Future ve
18bd0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
18be0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 might.** make u
18bf0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c se of additional
18c00 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d special filenam
18c10 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 es that begin wi
18c20 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 th the ":" chara
18c30 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 cter..** It is r
18c40 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
18c50 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 when a database
18c60 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c filename actuall
18c70 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 y does begin wit
18c80 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 h.** a ":" chara
18c90 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 cter you should
18ca0 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e prefix the filen
18cb0 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e ame with a pathn
18cc0 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 ame such as.** "
18cd0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 ./" to avoid amb
18ce0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 iguity..**.** If
18cf0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
18d00 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
18d10 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
18d20 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f , temporary.** o
18d30 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 n-disk database
18d40 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e will be created.
18d50 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 This private d
18d60 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a atabase will be.
18d70 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
18d80 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e deleted as soon
18d90 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 as the database
18da0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
18db0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 losed..**.** The
18dc0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
18dd0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
18de0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 n_v2() is the na
18df0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 me of the.** [sq
18e00 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
18e10 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 t that defines t
18e20 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
18e30 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 tem interface th
18e40 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 at.** the new da
18e50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18e60 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 n should use. I
18e70 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
18e80 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e ameter is.** a N
18e90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
18ea0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
18eb0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
18ec0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a t is used..**.**
18ed0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
18ee0 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 ows users:</b>
18ef0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 The encoding use
18f00 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 d for the filena
18f10 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f me argument.** o
18f20 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 f sqlite3_open()
18f30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
18f40 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 n_v2() must be U
18f50 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 TF-8, not whatev
18f60 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 er.** codepage i
18f70 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 s currently defi
18f80 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 ned. Filenames
18f90 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 containing inter
18fa0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 national.** char
18fb0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 acters must be c
18fc0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d onverted to UTF-
18fd0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 8 prior to passi
18fe0 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 ng them into.**
18ff0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
19000 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
19010 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 2()..**.** Requi
19020 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
19030 37 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 701] [H12702] [H
19040 31 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 12703] [H12704]
19050 5b 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37 [H12706] [H12707
19060 5d 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37 ] [H12709] [H127
19070 31 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 11].** [H12712]
19080 5b 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34 [H12713] [H12714
19090 5d 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37 ] [H12717] [H127
190a0 31 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 19] [H12721] [H1
190b0 32 37 32 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 2723].*/.SQLITE_
190c0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
190d0 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 open(. const ch
190e0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
190f0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
19100 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
19110 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
19120 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
19130 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
19140 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f le */.);.SQLITE_
19150 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
19160 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 open16(. const
19170 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 void *filename,
19180 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 /* Database fi
19190 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 lename (UTF-16)
191a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 */. sqlite3 **p
191b0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 pDb /*
191c0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 OUT: SQLite db h
191d0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 andle */.);.SQLI
191e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
191f0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f e3_open_v2(. co
19200 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
19210 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
19220 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
19230 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
19240 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 **ppDb,
19250 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
19260 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e b handle */. in
19270 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 t flags,
19280 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a /* Flags *
19290 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
192a0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e zVfs /* N
192b0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c ame of VFS modul
192c0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a e to use */.);..
192d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
192e0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 Error Codes And
192f0 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 Messages {H12800
19300 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S60200>.**.**
19310 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 The sqlite3_err
19320 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 code() interface
19330 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
19340 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 eric [result cod
19350 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 e] or.** [extend
19360 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
19370 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 for the most rec
19380 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 ent failed sqlit
19390 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a e3_* API call.**
193a0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
193b0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
193c0 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 nection]. If a p
193d0 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 rior API call fa
193e0 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 iled.** but the
193f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 most recent API
19400 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 call succeeded,
19410 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
19420 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 from.** sqlite3
19430 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e _errcode() is un
19440 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 defined. The sq
19450 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
19460 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 rrcode().** inte
19470 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d rface is the sam
19480 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 e except that it
19490 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
194a0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the .** [extende
194b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 d result code] e
194c0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 ven when extende
194d0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
194e0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a re.** disabled..
194f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
19500 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 3_errmsg() and s
19510 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
19520 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 ) return English
19530 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 -language.** tex
19540 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 t that describes
19550 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 the error, as e
19560 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 ither UTF-8 or U
19570 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 TF-16 respective
19580 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f ly..** Memory to
19590 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 hold the error
195a0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 message string i
195b0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e s managed intern
195c0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ally..** The app
195d0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f lication does no
195e0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 t need to worry
195f0 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 about freeing th
19600 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 e result..** How
19610 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 ever, the error
19620 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 string might be
19630 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 overwritten or d
19640 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a eallocated by.**
19650 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
19660 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 s to other SQLit
19670 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 e interface func
19680 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 tions..**.** Whe
19690 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 n the serialized
196a0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
196b0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 ] is in use, it
196c0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 might be the.**
196d0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f case that a seco
196e0 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 nd error occurs
196f0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 on a separate th
19700 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a read in between.
19710 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 ** the time of t
19720 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 he first error a
19730 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 nd the call to t
19740 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e hese interfaces.
19750 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 .** When that ha
19760 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e ppens, the secon
19770 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 d error will be
19780 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 reported since t
19790 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 hese.** interfac
197a0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 es always report
197b0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
197c0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f result. To avo
197d0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 id.** this, each
197e0 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 thread can obta
197f0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 in exclusive use
19800 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
19810 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a e connection] D.
19820 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b ** by invoking [
19830 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
19840 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ter]([sqlite3_db
19850 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f _mutex](D)) befo
19860 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 re beginning.**
19870 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 to use D and inv
19880 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
19890 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c utex_leave]([sql
198a0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
198b0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 )) after.** all
198c0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 calls to the int
198d0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 erfaces listed h
198e0 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 ere are complete
198f0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 d..**.** If an i
19900 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 nterface fails w
19910 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 ith SQLITE_MISUS
19920 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 E, that means th
19930 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 e interface.** w
19940 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 as invoked incor
19950 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 rectly by the ap
19960 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 plication. In t
19970 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a hat case, the.**
19980 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
19990 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d message may or m
199a0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a ay not be set..*
199b0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
199c0 73 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b s:.** [H12801] [
199d0 48 31 32 38 30 32 5d 20 5b 48 31 32 38 30 33 5d H12802] [H12803]
199e0 20 5b 48 31 32 38 30 37 5d 20 5b 48 31 32 38 30 [H12807] [H1280
199f0 38 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 53 8] [H12809].*/.S
19a00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
19a10 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 lite3_errcode(sq
19a20 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 lite3 *db);.SQLI
19a30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
19a40 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
19a50 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
19a60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
19a70 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
19a80 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a _errmsg(sqlite3*
19a90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
19aa0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
19ab0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 3_errmsg16(sqlit
19ac0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
19ad0 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 I3REF: SQL State
19ae0 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 ment Object {H13
19af0 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 000} <H13010>.**
19b00 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 KEYWORDS: {prep
19b10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 ared statement}
19b20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d {prepared statem
19b30 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 ents}.**.** An i
19b40 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
19b50 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
19b60 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 s a single SQL s
19b70 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 tatement..** Thi
19b80 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 s object is vari
19b90 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 ously known as a
19ba0 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 "prepared state
19bb0 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 ment" or a.** "c
19bc0 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 ompiled SQL stat
19bd0 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 ement" or simply
19be0 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 as a "statement
19bf0 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 "..**.** The lif
19c00 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 e of a statement
19c10 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d object goes som
19c20 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 ething like this
19c30 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 :.**.** <ol>.**
19c40 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 <li> Create the
19c50 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 object using [sq
19c60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
19c70 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 ()] or a related
19c80 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f .** functio
19c90 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 n..** <li> Bind
19ca0 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 values to [host
19cb0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e parameters] usin
19cc0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 g the sqlite3_bi
19cd0 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 nd_*().** i
19ce0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c nterfaces..** <l
19cf0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 i> Run the SQL b
19d00 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
19d10 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f e3_step()] one o
19d20 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a r more times..**
19d30 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 <li> Reset the
19d40 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 statement using
19d50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
19d60 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a ] then go back.*
19d70 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 * to step 2
19d80 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 . Do this zero
19d90 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a or more times..*
19da0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 * <li> Destroy t
19db0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 he object using
19dc0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
19dd0 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a e()]..** </ol>.*
19de0 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f *.** Refer to do
19df0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 cumentation on i
19e00 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 ndividual method
19e10 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 s above for addi
19e20 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
19e30 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 ation..*/.typede
19e40 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
19e50 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 _stmt sqlite3_st
19e60 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 mt;../*.** CAPI3
19e70 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 REF: Run-time Li
19e80 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 mits {H12760} <S
19e90 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 20600>.**.** Thi
19ea0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
19eb0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 ws the size of v
19ec0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 arious construct
19ed0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a s to be limited.
19ee0 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 ** on a connecti
19ef0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e on by connection
19f00 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 basis. The fir
19f10 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
19f20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
19f30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f connection] who
19f40 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 se limit is to b
19f50 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 e set or queried
19f60 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 . The.** second
19f70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e parameter is on
19f80 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 e of the [limit
19f90 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 categories] that
19fa0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 define a.** cla
19fb0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 ss of constructs
19fc0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 to be size limi
19fd0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 ted. The third
19fe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
19ff0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f .** new limit fo
1a000 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 r that construct
1a010 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 . The function
1a020 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 returns the old
1a030 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 limit..**.** If
1a040 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 the new limit is
1a050 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 a negative numb
1a060 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 er, the limit is
1a070 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 unchanged..** F
1a080 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 or the limit cat
1a090 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f egory of SQLITE_
1a0a0 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 LIMIT_XYZ there
1a0b0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 is a .** [limits
1a0c0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f | hard upper bo
1a0d0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 und].** set by a
1a0e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 compile-time C
1a0f0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
1a100 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 ro named .** [li
1a110 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 mits | SQLITE_MA
1a120 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 X_XYZ]..** (The
1a130 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 "_LIMIT_" in the
1a140 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 name is changed
1a150 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a to "_MAX_".).**
1a160 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 Attempts to inc
1a170 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 rease a limit ab
1a180 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 ove its hard upp
1a190 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 er bound are.**
1a1a0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 silently truncat
1a1b0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 ed to the hard u
1a1c0 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a pper limit..**.*
1a1d0 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 * Run time limit
1a1e0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
1a1f0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 or use in applic
1a200 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 ations that mana
1a210 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 ge.** both their
1a220 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 own internal da
1a230 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 tabase and also
1a240 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 databases that a
1a250 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a re controlled.**
1a260 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 by untrusted ex
1a270 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 ternal sources.
1a280 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c An example appl
1a290 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 ication might be
1a2a0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 a.** web browse
1a2b0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f r that has its o
1a2c0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 wn databases for
1a2d0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 storing history
1a2e0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 and.** separate
1a2f0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 databases contr
1a300 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 olled by JavaScr
1a310 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ipt applications
1a320 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f downloaded.** o
1a330 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e ff the Internet.
1a340 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 The internal d
1a350 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 atabases can be
1a360 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 given the.** lar
1a370 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 ge, default limi
1a380 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d ts. Databases m
1a390 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e anaged by extern
1a3a0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a al sources can.*
1a3b0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 * be given much
1a3c0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 smaller limits d
1a3d0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 esigned to preve
1a3e0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 nt a denial of s
1a3f0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b ervice.** attack
1a400 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 . Developers mi
1a410 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f ght also want to
1a420 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 use the [sqlite
1a430 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1a440 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
1a450 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 to further cont
1a460 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 rol untrusted SQ
1a470 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 L. The size of
1a480 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
1a490 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e created by an un
1a4a0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 trusted script c
1a4b0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 an be contained
1a4c0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 using the.** [ma
1a4d0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
1a4e0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 RAGMA]..**.** Ne
1a4f0 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 w run-time limit
1a500 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 categories may
1a510 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
1a520 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a re releases..**.
1a530 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
1a540 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b 48 31 .** [H12762] [H1
1a550 32 37 36 36 5d 20 5b 48 31 32 37 36 39 5d 0a 2a 2766] [H12769].*
1a560 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1a570 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 sqlite3_limit(s
1a580 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c qlite3*, int id,
1a590 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f int newVal);../
1a5a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1a5b0 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 un-Time Limit Ca
1a5c0 74 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 tegories {H12790
1a5d0 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 } <H12760>.** KE
1a5e0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 YWORDS: {limit c
1a5f0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 ategory} {*limit
1a600 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a categories}.**.
1a610 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
1a620 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 ts define variou
1a630 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 s performance li
1a640 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e mits.** that can
1a650 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 be lowered at r
1a660 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 un-time using [s
1a670 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e qlite3_limit()].
1a680 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 .** The synopsis
1a690 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 of the meanings
1a6a0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 of the various
1a6b0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 limits is shown
1a6c0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 below..** Additi
1a6d0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
1a6e0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 is available at
1a6f0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 [limits | Limit
1a700 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a s in SQLite]..**
1a710 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e .** <dl>.** <dt>
1a720 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
1a730 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
1a740 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 The maximum size
1a750 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f of any string o
1a760 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 r BLOB or table
1a770 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c row.<dd>.**.** <
1a780 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1a790 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a SQL_LENGTH</dt>.
1a7a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1a7b0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 um length of an
1a7c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f SQL statement.</
1a7d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
1a7e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
1a7f0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 N</dt>.** <dd>Th
1a800 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
1a810 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
1a820 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f table definitio
1a830 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 n or in the.** r
1a840 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
1a850 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d SELECT] or the m
1a860 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
1a870 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 columns in an i
1a880 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e ndex.** or in an
1a890 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f ORDER BY or GRO
1a8a0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 UP BY clause.</d
1a8b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
1a8c0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
1a8d0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
1a8e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
1a8f0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 th of the parse
1a900 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 tree on any expr
1a910 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a ession.</dd>.**.
1a920 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
1a930 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
1a940 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ECT</dt>.** <dd>
1a950 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1a960 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 er of terms in a
1a970 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 compound SELECT
1a980 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e statement.</dd>
1a990 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
1a9a0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c E_LIMIT_VDBE_OP<
1a9b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1a9c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
1a9d0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 f instructions i
1a9e0 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 n a virtual mach
1a9f0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 ine program.** u
1aa00 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
1aa10 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
1aa20 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 t.</dd>.**.** <d
1aa30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 t>SQLITE_LIMIT_F
1aa40 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e UNCTION_ARG</dt>
1aa50 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1aa60 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 mum number of ar
1aa70 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e guments on a fun
1aa80 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ction.</dd>.**.*
1aa90 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
1aaa0 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e IT_ATTACHED</dt>
1aab0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1aac0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 mum number of [A
1aad0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 TTACH | attached
1aae0 20 64 61 74 61 62 61 73 65 73 5d 2e 3c 2f 64 64 databases].</dd
1aaf0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
1ab00 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
1ab10 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 TTERN_LENGTH</dt
1ab20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
1ab30 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 imum length of t
1ab40 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d he pattern argum
1ab50 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 ent to the [LIKE
1ab60 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f ] or.** [GLOB] o
1ab70 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a perators.</dd>.*
1ab80 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
1ab90 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
1aba0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 UMBER</dt>.** <d
1abb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
1abc0 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 mber of variable
1abd0 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 s in an SQL stat
1abe0 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a ement that can.*
1abf0 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e * be bound.</dd>
1ac00 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
1ac10 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
1ac20 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
1ac30 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
1ac40 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e pth of recursion
1ac50 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f for triggers.</
1ac60 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a dd>.** </dl>.*/.
1ac70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1ac80 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 IMIT_LENGTH
1ac90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
1aca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1acb0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
1acc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1acd0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
1ace0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 _LIMIT_COLUMN
1acf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1ad00 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
1ad10 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
1ad20 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
1ad30 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
1ad40 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
1ad50 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 D_SELECT
1ad60 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
1ad70 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
1ad80 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 P
1ad90 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 5.#define SQ
1ada0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
1adb0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 ION_ARG
1adc0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
1add0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
1ade0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 CHED
1adf0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 7.#define
1ae00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
1ae10 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
1ae20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
1ae30 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 SQLITE_LIMIT_VA
1ae40 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 RIABLE_NUMBER
1ae50 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
1ae60 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 e SQLITE_LIMIT_T
1ae70 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 RIGGER_DEPTH
1ae80 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 10../*.*
1ae90 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 * CAPI3REF: Comp
1aea0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 iling An SQL Sta
1aeb0 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 tement {H13010}
1aec0 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S10000>.** KEYW
1aed0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 ORDS: {SQL state
1aee0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a ment compiler}.*
1aef0 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 *.** To execute
1af00 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 an SQL query, it
1af10 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 must first be c
1af20 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 ompiled into a b
1af30 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 yte-code.** prog
1af40 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 ram using one of
1af50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
1af60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
1af70 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c argument, "db",
1af80 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 is a [database
1af90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 connection] obta
1afa0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 ined from a.** p
1afb0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 rior successful
1afc0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
1afd0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1afe0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 e3_open_v2()] or
1aff0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
1b000 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 n16()]. The dat
1b010 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1b020 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 must not have b
1b030 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a een closed..**.*
1b040 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
1b050 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 ument, "zSql", i
1b060 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 s the statement
1b070 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 to be compiled,
1b080 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 encoded.** as ei
1b090 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
1b0a0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 F-16. The sqlit
1b0b0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 e3_prepare() and
1b0c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1b0d0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 _v2().** interfa
1b0e0 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 ces use UTF-8, a
1b0f0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
1b100 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 re16() and sqlit
1b110 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1b120 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e ).** use UTF-16.
1b130 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 .**.** If the nB
1b140 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 yte argument is
1b150 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 less than zero,
1b160 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 then zSql is rea
1b170 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 d up to the.** f
1b180 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
1b190 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 ator. If nByte i
1b1a0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
1b1b0 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d then it is the m
1b1c0 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 aximum.** number
1b1d0 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 of bytes read
1b1e0 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e from zSql. When
1b1f0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 nByte is non-ne
1b200 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a gative, the.** z
1b210 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 Sql string ends
1b220 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 at either the fi
1b230 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c rst '\000' or '\
1b240 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 u0000' character
1b250 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 or.** the nByte
1b260 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 -th byte, whiche
1b270 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e ver comes first.
1b280 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b If the caller k
1b290 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 nows.** that the
1b2a0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 supplied string
1b2b0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 is nul-terminat
1b2c0 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 ed, then there i
1b2d0 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 s a small.** per
1b2e0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 formance advanta
1b2f0 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 ge to be gained
1b300 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 by passing an nB
1b310 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 yte parameter th
1b320 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 at.** is equal t
1b330 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 o the number of
1b340 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 bytes in the inp
1b350 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 ut string <i>inc
1b360 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 luding</i>.** th
1b370 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 e nul-terminator
1b380 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 bytes..**.** If
1b390 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e pzTail is not N
1b3a0 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c ULL then *pzTail
1b3b0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e is made to poin
1b3c0 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 t to the first b
1b3d0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 yte.** past the
1b3e0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 end of the first
1b3f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
1b400 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 n zSql. These r
1b410 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 outines only.**
1b420 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 compile the firs
1b430 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a t statement in z
1b440 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 Sql, so *pzTail
1b450 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
1b460 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 to.** what rema
1b470 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a ins uncompiled..
1b480 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 **.** *ppStmt is
1b490 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
1b4a0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 o a compiled [pr
1b4b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1b4c0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a ] that can be.**
1b4d0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 executed using
1b4e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1b4f0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 61 . If there is a
1b500 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 n error, *ppStmt
1b510 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 is set.** to NU
1b520 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 LL. If the inpu
1b530 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 t text contains
1b540 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 no SQL (if the i
1b550 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 nput is an empty
1b560 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 .** string or a
1b570 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 comment) then *p
1b580 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 pStmt is set to
1b590 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c NULL..** The cal
1b5a0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 ling procedure i
1b5b0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
1b5c0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 r deleting the c
1b5d0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 ompiled.** SQL s
1b5e0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
1b5f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
1b600 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 ()] after it has
1b610 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
1b620 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 t..** ppStmt may
1b630 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a not be NULL..**
1b640 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 .** On success,
1b650 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
1b660 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 eturned, otherwi
1b670 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 se an [error cod
1b680 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
1b690 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1b6a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 3_prepare_v2() a
1b6b0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
1b6c0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 re16_v2() interf
1b6d0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f aces are.** reco
1b6e0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 mmended for all
1b6f0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 new programs. Th
1b700 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 e two older inte
1b710 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 rfaces are retai
1b720 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 ned.** for backw
1b730 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
1b740 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 ty, but their us
1b750 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 e is discouraged
1b760 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 ..** In the "v2"
1b770 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
1b780 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
1b790 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 ent.** that is r
1b7a0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 eturned (the [sq
1b7b0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
1b7c0 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 ct) contains a c
1b7d0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 opy of the.** or
1b7e0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e iginal SQL text.
1b7f0 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 This causes the
1b800 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1b810 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a ] interface to.*
1b820 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 * behave differe
1b830 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 ntly in three wa
1b840 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a ys:.**.** <ol>.*
1b850 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 * <li>.** If the
1b860 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
1b870 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 changes, instea
1b880 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b d of returning [
1b890 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 SQLITE_SCHEMA] a
1b8a0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 s it.** always u
1b8b0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 sed to do, [sqli
1b8c0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
1b8d0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
1b8e0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c ecompile the SQL
1b8f0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e .** statement an
1b900 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 d try to run it
1b910 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 again. If the s
1b920 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 chema has change
1b930 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 d in.** a way th
1b940 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 at makes the sta
1b950 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 tement no longer
1b960 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 valid, [sqlite3
1b970 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 _step()] will st
1b980 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 ill.** return [S
1b990 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 QLITE_SCHEMA].
1b9a0 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c But unlike the l
1b9b0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 egacy behavior,
1b9c0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 [SQLITE_SCHEMA]
1b9d0 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 is.** now a fata
1b9e0 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e l error. Callin
1b9f0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
1ba00 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 re_v2()] again w
1ba10 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 ill not make the
1ba20 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 .** error go awa
1ba30 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 y. Note: use [s
1ba40 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
1ba50 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 to find the tex
1ba60 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 t.** of the pars
1ba70 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 ing error that r
1ba80 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 esults in an [SQ
1ba90 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 LITE_SCHEMA] ret
1baa0 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a urn..** </li>.**
1bab0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e .** <li>.** When
1bac0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
1bad0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
1bae0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f )] will return o
1baf0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c ne of the detail
1bb00 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 ed.** [error cod
1bb10 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 es] or [extended
1bb20 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 error codes].
1bb30 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 The legacy behav
1bb40 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 ior was that.**
1bb50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1bb60 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 would only retu
1bb70 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 rn a generic [SQ
1bb80 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 LITE_ERROR] resu
1bb90 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 lt code.** and y
1bba0 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f ou would have to
1bbb0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 make a second c
1bbc0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
1bbd0 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 reset()] in orde
1bbe0 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 r.** to find the
1bbf0 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 underlying caus
1bc00 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d e of the problem
1bc10 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 . With the "v2"
1bc20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 prepare.** inter
1bc30 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 faces, the under
1bc40 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 lying reason for
1bc50 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 the error is re
1bc60 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
1bc70 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a ly..** </li>.**.
1bc80 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
1bc90 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 5b 70 he value of a [p
1bca0 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 arameter | host
1bcb0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 parameter] in th
1bcc0 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d e WHERE clause m
1bcd0 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74 ight.** change t
1bce0 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f he query plan fo
1bcf0 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 r a statement, t
1bd00 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
1bd10 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61 75 74 6f t may be.** auto
1bd20 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 matically recomp
1bd30 69 6c 65 64 20 28 61 73 20 69 66 20 74 68 65 72 iled (as if ther
1bd40 65 20 68 61 64 20 62 65 65 6e 20 61 20 73 63 68 e had been a sch
1bd50 65 6d 61 20 63 68 61 6e 67 65 29 20 6f 6e 20 74 ema change) on t
1bd60 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 5b 73 71 he first .** [sq
1bd70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 lite3_step()] ca
1bd80 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 ll following any
1bd90 20 63 68 61 6e 67 65 20 74 6f 20 74 68 65 20 0a change to the .
1bda0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
1bdb0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 _text | bindings
1bdc0 5d 20 6f 66 20 74 68 65 20 5b 70 61 72 61 6d 65 ] of the [parame
1bdd0 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a ter]. .** </li>.
1bde0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 ** </ol>.**.** R
1bdf0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
1be00 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32 [H13011] [H13012
1be10 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30 ] [H13013] [H130
1be20 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 14] [H13015] [H1
1be30 33 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 3016] [H13019] [
1be40 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 53 51 H13021].**.*/.SQ
1be50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1be60 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 ite3_prepare(.
1be70 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
1be80 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
1be90 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
1bea0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
1beb0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
1bec0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 tatement, UTF-8
1bed0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
1bee0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
1bef0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
1bf00 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
1bf10 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
1bf20 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
1bf30 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
1bf40 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
1bf50 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1bf60 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
1bf70 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
1bf80 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
1bf90 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 zSql */.);.SQLI
1bfa0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1bfb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 e3_prepare_v2(.
1bfc0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1bfd0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
1bfe0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
1bff0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
1c000 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
1c010 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
1c020 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
1c030 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
1c040 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
1c050 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
1c060 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
1c070 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
1c080 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
1c090 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
1c0a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1c0b0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
1c0c0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
1c0d0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
1c0e0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c f zSql */.);.SQL
1c0f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1c100 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 te3_prepare16(.
1c110 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1c120 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
1c130 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
1c140 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
1c150 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
1c160 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
1c170 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
1c180 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
1c190 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
1c1a0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
1c1b0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
1c1c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
1c1d0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
1c1e0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
1c1f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
1c200 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
1c210 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
1c220 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
1c230 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 of zSql */.);.SQ
1c240 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1c250 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1c260 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
1c270 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
1c280 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
1c290 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
1c2a0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
1c2b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
1c2c0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
1c2d0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
1c2e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
1c2f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
1c300 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
1c310 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
1c320 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
1c330 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
1c340 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1c350 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
1c360 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
1c370 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
1c380 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
1c390 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1c3a0 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 F: Retrieving St
1c3b0 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33 atement SQL {H13
1c3c0 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 100} <H13000>.**
1c3d0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
1c3e0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ce can be used t
1c3f0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 o retrieve a sav
1c400 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f ed copy of the o
1c410 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 riginal.** SQL t
1c420 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 ext used to crea
1c430 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
1c440 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 tatement] if tha
1c450 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a t statement was.
1c460 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e ** compiled usin
1c470 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 g either [sqlite
1c480 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1c490 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
1c4a0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
1c4b0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
1c4c0 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b 48 31 .** [H13101] [H1
1c4d0 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d 0a 2a 3102] [H13103].*
1c4e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
1c4f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
1c500 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d _sql(sqlite3_stm
1c510 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
1c520 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 * CAPI3REF: Dyna
1c530 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 mically Typed Va
1c540 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 lue Object {H150
1c550 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 00} <S20200>.**
1c560 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 KEYWORDS: {prote
1c570 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
1c580 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 ue} {unprotected
1c590 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a sqlite3_value}.
1c5a0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 **.** SQLite use
1c5b0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 s the sqlite3_va
1c5c0 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 lue object to re
1c5d0 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 present all valu
1c5e0 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 es.** that can b
1c5f0 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 e stored in a da
1c600 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 tabase table. SQ
1c610 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 Lite uses dynami
1c620 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 c typing.** for
1c630 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 the values it st
1c640 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f ores. Values sto
1c650 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 red in sqlite3_v
1c660 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 alue objects.**
1c670 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c can be integers,
1c680 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
1c690 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c values, strings,
1c6a0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e BLOBs, or NULL.
1c6b0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 .**.** An sqlite
1c6c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 3_value object m
1c6d0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 ay be either "pr
1c6e0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 otected" or "unp
1c6f0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f rotected"..** So
1c700 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 me interfaces re
1c710 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 quire a protecte
1c720 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
1c730 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 Other interfac
1c740 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 es.** will accep
1c750 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 t either a prote
1c760 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f cted or an unpro
1c770 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
1c780 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 alue..** Every i
1c790 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 nterface that ac
1c7a0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 cepts sqlite3_va
1c7b0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 lue arguments sp
1c7c0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 ecifies.** wheth
1c7d0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 er or not it req
1c7e0 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 uires a protecte
1c7f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
1c800 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 .**.** The terms
1c810 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 "protected" and
1c820 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 "unprotected" r
1c830 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 efer to whether
1c840 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 or not.** a mute
1c850 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e x is held. A in
1c860 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 ternal mutex is
1c870 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 held for a prote
1c880 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
1c890 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 value object but
1c8a0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c no mutex is hel
1c8b0 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 d for an unprote
1c8c0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
1c8d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 value object. I
1c8e0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
1c8f0 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c iled to be singl
1c900 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 e-threaded.** (w
1c910 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 ith [SQLITE_THRE
1c920 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 ADSAFE=0] and wi
1c930 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 th [sqlite3_thre
1c940 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e adsafe()] return
1c950 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 ing 0).** or if
1c960 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e SQLite is run in
1c970 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 one of reduced
1c980 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 mutex modes .**
1c990 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
1c9a0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 INGLETHREAD] or
1c9b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
1c9c0 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 ULTITHREAD].** t
1c9d0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 hen there is no
1c9e0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 distinction betw
1c9f0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e een protected an
1ca00 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a d unprotected.**
1ca10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1ca20 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 bjects and they
1ca30 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 can be used inte
1ca40 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f rchangeably. Ho
1ca50 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 wever,.** for ma
1ca60 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 ximum code porta
1ca70 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 bility it is rec
1ca80 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
1ca90 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 plications.** st
1caa0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 ill make the dis
1cab0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
1cac0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 between protect
1cad0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 ed and unprotect
1cae0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
1caf0 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e lue objects even
1cb00 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 when not strict
1cb10 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a ly required..**.
1cb20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ** The sqlite3_v
1cb30 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 alue objects tha
1cb40 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 t are passed as
1cb50 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 parameters into
1cb60 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
1cb70 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 ation of [applic
1cb80 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
1cb90 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 L functions] are
1cba0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 protected..** T
1cbb0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
1cbc0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
1cbd0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
1cbe0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
1cbf0 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a is unprotected..
1cc00 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 ** Unprotected s
1cc10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1cc20 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 ects may only be
1cc30 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 used with.** [s
1cc40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
1cc50 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 lue()] and [sqli
1cc60 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 te3_bind_value()
1cc70 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 ]..** The [sqlit
1cc80 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 e3_value_blob |
1cc90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 sqlite3_value_ty
1cca0 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a pe()] family of.
1ccb0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 ** interfaces re
1ccc0 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 quire protected
1ccd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1cce0 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 jects..*/.typede
1ccf0 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c f struct Mem sql
1cd00 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a ite3_value;../*.
1cd10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c ** CAPI3REF: SQL
1cd20 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 Function Contex
1cd30 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 t Object {H16001
1cd40 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
1cd50 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 The context in
1cd60 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e which an SQL fun
1cd70 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 ction executes i
1cd80 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a s stored in an.*
1cd90 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 * sqlite3_contex
1cda0 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 t object. A poi
1cdb0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 nter to an sqlit
1cdc0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
1cdd0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 t.** is always f
1cde0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
1cdf0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 o [application-d
1ce00 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
1ce10 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 ions]..** The ap
1ce20 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
1ce30 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 d SQL function i
1ce40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
1ce50 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 ll pass this.**
1ce60 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 pointer through
1ce70 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 into calls to [s
1ce80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
1ce90 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 t | sqlite3_resu
1cea0 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 lt()],.** [sqlit
1ceb0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
1cec0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 text()], [sqlite
1ced0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 3_user_data()],.
1cee0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
1cef0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d ext_db_handle()]
1cf00 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 , [sqlite3_get_a
1cf10 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e uxdata()],.** an
1cf20 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 d/or [sqlite3_se
1cf30 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f t_auxdata()]..*/
1cf40 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
1cf50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
1cf60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b sqlite3_context;
1cf70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1cf80 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 : Binding Values
1cf90 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
1cfa0 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d tements {H13500}
1cfb0 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 <S70300>.** KEY
1cfc0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 WORDS: {host par
1cfd0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 ameter} {host pa
1cfe0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 rameters} {host
1cff0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a parameter name}.
1d000 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 ** KEYWORDS: {SQ
1d010 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 L parameter} {SQ
1d020 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 L parameters} {p
1d030 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 arameter binding
1d040 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 }.**.** In the S
1d050 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 QL strings input
1d060 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 to [sqlite3_pre
1d070 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 pare_v2()] and i
1d080 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 ts variants,.**
1d090 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 literals may be
1d0a0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 replaced by a [p
1d0b0 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d arameter] that m
1d0c0 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f atches one of fo
1d0d0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c llowing.** templ
1d0e0 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ates:.**.** <ul>
1d0f0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c .** <li> ?.** <
1d100 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 li> ?NNN.** <li
1d110 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > :VVV.** <li>
1d120 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 @VVV.** <li> $
1d130 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VVV.** </ul>.**.
1d140 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 ** In the templa
1d150 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 tes above, NNN r
1d160 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 epresents an int
1d170 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a eger literal,.**
1d180 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 and VVV represe
1d190 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 nts an alphanume
1d1a0 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e 20 20 ric identifer.
1d1b0 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 The values of th
1d1c0 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ese.** parameter
1d1d0 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 s (also called "
1d1e0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
1d1f0 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 ames" or "SQL pa
1d200 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 rameters").** ca
1d210 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 n be set using t
1d220 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1d230 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 *() routines def
1d240 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a ined here..**.**
1d250 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
1d260 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
1d270 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
1d280 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a ines is always.*
1d290 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 * a pointer to t
1d2a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
1d2b0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
1d2c0 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 d from.** [sqlit
1d2d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1d2e0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
1d2f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
1d300 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
1d310 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
1d320 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f SQL parameter to
1d330 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 be set..** The
1d340 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 leftmost SQL par
1d350 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e ameter has an in
1d360 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 dex of 1. When
1d370 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a the same named.*
1d380 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 * SQL parameter
1d390 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
1d3a0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 n once, second a
1d3b0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a nd subsequent.**
1d3c0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 occurrences hav
1d3d0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 e the same index
1d3e0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 as the first oc
1d3f0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 currence..** The
1d400 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 index for named
1d410 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 parameters can
1d420 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 be looked up usi
1d430 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
1d440 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1d450 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 r_index()] API i
1d460 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 f desired. The
1d470 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e index.** for "?N
1d480 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 NN" parameters i
1d490 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e s the value of N
1d4a0 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 NN..** The NNN v
1d4b0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 alue must be bet
1d4c0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b ween 1 and the [
1d4d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
1d4e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 .** parameter [S
1d4f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
1d500 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 ABLE_NUMBER] (de
1d510 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 fault value: 999
1d520 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 )..**.** The thi
1d530 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 rd argument is t
1d540 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 he value to bind
1d550 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
1d560 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 r..**.** In thos
1d570 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 e routines that
1d580 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
1d590 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
1d5a0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
1d5b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
1d5c0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
1d5d0 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
1d5e0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
1d5f0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 number of <u>byt
1d600 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 es</u> in the va
1d610 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d lue, not the num
1d620 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
1d630 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 s..** If the fou
1d640 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
1d650 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c negative, the l
1d660 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 ength of the str
1d670 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 ing is.** the nu
1d680 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 mber of bytes up
1d690 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 to the first ze
1d6a0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a ro terminator..*
1d6b0 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 *.** The fifth a
1d6c0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
1d6d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 e3_bind_blob(),
1d6e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
1d6f0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 t(), and.** sqli
1d700 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
1d710 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f ) is a destructo
1d720 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 r used to dispos
1d730 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
1d740 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 .** string after
1d750 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 SQLite has fini
1d760 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 shed with it. If
1d770 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
1d780 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 ent is.** the sp
1d790 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c ecial value [SQL
1d7a0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 ITE_STATIC], the
1d7b0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 n SQLite assumes
1d7c0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 that the.** inf
1d7d0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 ormation is in s
1d7e0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 tatic, unmanaged
1d7f0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
1d800 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 not need to be f
1d810 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 reed..** If the
1d820 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
1d830 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
1d840 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
1d850 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
1d860 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
1d870 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
1d880 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
1d890 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
1d8a0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
1d8b0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
1d8c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ns..**.** The sq
1d8d0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
1d8e0 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 lob() routine bi
1d8f0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 nds a BLOB of le
1d900 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 ngth N that.** i
1d910 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 s filled with ze
1d920 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f roes. A zeroblo
1d930 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 b uses a fixed a
1d940 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a mount of memory.
1d950 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 ** (just an inte
1d960 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 ger to hold its
1d970 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 size) while it i
1d980 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 s being processe
1d990 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 d..** Zeroblobs
1d9a0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 are intended to
1d9b0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f serve as placeho
1d9c0 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 lders for BLOBs
1d9d0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 whose.** content
1d9e0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 is later writte
1d9f0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
1da00 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
1da10 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
1da20 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a I/O] routines..
1da30 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 ** A negative va
1da40 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f lue for the zero
1da50 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 blob results in
1da60 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
1da70 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 OB..**.** The sq
1da80 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
1da90 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
1daa0 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 called after.**
1dab0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1dac0 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 _v2()] (and its
1dad0 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 variants) or [sq
1dae0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 lite3_reset()] a
1daf0 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 nd.** before [sq
1db00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
1db10 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e * Bindings are n
1db20 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 ot cleared by th
1db30 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
1db40 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 ()] routine..**
1db50 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 Unbound paramete
1db60 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 rs are interpret
1db70 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ed as NULL..**.*
1db80 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
1db90 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1dba0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
1dbb0 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 r an error code
1dbc0 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 if.** anything g
1dbd0 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c oes wrong. [SQL
1dbe0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 ITE_RANGE] is re
1dbf0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 turned if the pa
1dc00 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 rameter.** index
1dc10 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1dc20 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d . [SQLITE_NOMEM
1dc30 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
1dc40 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e malloc() fails.
1dc50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 .** [SQLITE_MISU
1dc60 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 SE] might be ret
1dc70 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 urned if these r
1dc80 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
1dc90 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 ed on a.** virtu
1dca0 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 al machine that
1dcb0 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 is the wrong sta
1dcc0 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 te or which has
1dcd0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e already been fin
1dce0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 alized..** Detec
1dcf0 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 tion of misuse i
1dd00 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 s unreliable. A
1dd10 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
1dd20 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a ld not depend.**
1dd30 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 on SQLITE_MISUS
1dd40 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 E returns. SQLI
1dd50 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 TE_MISUSE is int
1dd60 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 ended to indicat
1dd70 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 e a.** a logic e
1dd80 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c rror in the appl
1dd90 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 ication. Future
1dda0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
1ddb0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e ite might.** pan
1ddc0 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 ic rather than r
1ddd0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 eturn SQLITE_MIS
1dde0 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 USE..**.** See a
1ddf0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
1de00 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
1de10 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nt()],.** [sqlit
1de20 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1de30 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b r_name()], and [
1de40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1de50 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
1de60 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1de70 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30 36 5d nts:.** [H13506]
1de80 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 33 35 31 [H13509] [H1351
1de90 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48 31 33 2] [H13515] [H13
1dea0 35 31 38 5d 20 5b 48 31 33 35 32 31 5d 20 5b 48 518] [H13521] [H
1deb0 31 33 35 32 34 5d 20 5b 48 31 33 35 32 37 5d 0a 13524] [H13527].
1dec0 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48 31 33 ** [H13530] [H13
1ded0 35 33 33 5d 20 5b 48 31 33 35 33 36 5d 20 5b 48 533] [H13536] [H
1dee0 31 33 35 33 39 5d 20 5b 48 31 33 35 34 32 5d 20 13539] [H13542]
1def0 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 35 34 38 [H13545] [H13548
1df00 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a 2a 2f ] [H13551].**.*/
1df10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1df20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1df30 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
1df40 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
1df50 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
1df60 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
1df70 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
1df80 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 3_bind_double(sq
1df90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1dfa0 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 , double);.SQLIT
1dfb0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
1dfc0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 3_bind_int(sqlit
1dfd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 e3_stmt*, int, i
1dfe0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
1dff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
1e000 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
1e010 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 tmt*, int, sqlit
1e020 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 e3_int64);.SQLIT
1e030 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
1e040 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 3_bind_null(sqli
1e050 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
1e060 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1e070 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
1e080 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
1e090 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 int, const char
1e0a0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
1e0b0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
1e0c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
1e0d0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 3_bind_text16(sq
1e0e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1e0f0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
1e100 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
1e110 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
1e120 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
1e130 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
1e140 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
1e150 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 sqlite3_value*)
1e160 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
1e170 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
1e180 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 roblob(sqlite3_s
1e190 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e tmt*, int, int n
1e1a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1e1b0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 EF: Number Of SQ
1e1c0 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 L Parameters {H1
1e1d0 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 3600} <S70300>.*
1e1e0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
1e1f0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
1e200 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 find the number
1e210 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 of [SQL paramet
1e220 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 ers].** in a [pr
1e230 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1e240 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 ]. SQL paramete
1e250 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 rs are tokens of
1e260 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 the.** form "?"
1e270 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 , "?NNN", ":AAA"
1e280 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 , "$AAA", or "@A
1e290 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 AA" that serve a
1e2a0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 s.** placeholder
1e2b0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 s for values tha
1e2c0 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 t are [sqlite3_b
1e2d0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 ind_blob | bound
1e2e0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 ].** to the para
1e2f0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 meters at a late
1e300 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 r time..**.** Th
1e310 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 is routine actua
1e320 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 lly returns the
1e330 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 index of the lar
1e340 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 gest (rightmost)
1e350 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 .** parameter. F
1e360 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 or all forms exc
1e370 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 ept ?NNN, this w
1e380 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 ill correspond t
1e390 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 o the.** number
1e3a0 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 of unique parame
1e3b0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 ters. If parame
1e3c0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e ters of the ?NNN
1e3d0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 are used,.** th
1e3e0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 ere may be gaps
1e3f0 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a in the list..**.
1e400 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
1e410 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
1e420 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
1e430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
1e440 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
1e450 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
1e460 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1e470 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a ter_index()]..**
1e480 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1e490 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f :.** [H13601].*/
1e4a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1e4b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1e4c0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c ameter_count(sql
1e4d0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
1e4e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 .** CAPI3REF: Na
1e4f0 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 me Of A Host Par
1e500 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 ameter {H13620}
1e510 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S70300>.**.** T
1e520 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
1e530 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1e540 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1e550 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 n-th.** [SQL pa
1e560 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 rameter] in a [p
1e570 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1e580 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d t]..** SQL param
1e590 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
1e5a0 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 m "?NNN" or ":AA
1e5b0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
1e5c0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 "$AAA".** have a
1e5d0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 name which is t
1e5e0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 he string "?NNN"
1e5f0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 or ":AAA" or "@
1e600 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a AAA" or "$AAA".*
1e610 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a * respectively..
1e620 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 ** In other word
1e630 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 s, the initial "
1e640 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 :" or "$" or "@"
1e650 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e or "?".** is in
1e660 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f cluded as part o
1e670 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 f the name..** P
1e680 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
1e690 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 form "?" withou
1e6a0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e t a following in
1e6b0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 teger have no na
1e6c0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c me.** and are al
1e6d0 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 so referred to a
1e6e0 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 s "anonymous par
1e6f0 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 ameters"..**.**
1e700 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 The first host p
1e710 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 arameter has an
1e720 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 index of 1, not
1e730 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 0..**.** If the
1e740 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f value n is out o
1e750 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 f range or if th
1e760 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 e n-th parameter
1e770 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c is.** nameless,
1e780 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 then NULL is re
1e790 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 turned. The ret
1e7a0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a urned string is.
1e7b0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 ** always in UTF
1e7c0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e -8 encoding even
1e7d0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 if the named pa
1e7e0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f rameter was.** o
1e7f0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 riginally specif
1e800 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e ied as UTF-16 in
1e810 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e820 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 e16()] or.** [sq
1e830 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
1e840 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 v2()]..**.** See
1e850 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
1e860 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
1e870 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
1e880 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1e890 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 meter_count()],
1e8a0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
1e8b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
1e8c0 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 ndex()]..**.** R
1e8d0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
1e8e0 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a 53 51 4c 49 [H13621].*/.SQLI
1e8f0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
1e900 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f r *sqlite3_bind_
1e910 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 parameter_name(s
1e920 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1e930 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
1e940 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 REF: Index Of A
1e950 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 Parameter With A
1e960 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 Given Name {H13
1e970 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 640} <S70300>.**
1e980 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 .** Return the i
1e990 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 ndex of an SQL p
1e9a0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 arameter given i
1e9b0 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a ts name. The.**
1e9c0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 index value ret
1e9d0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c urned is suitabl
1e9e0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 e for use as the
1e9f0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d second.** param
1ea00 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
1ea10 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
1ea20 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a e3_bind()]. A z
1ea30 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ero.** is return
1ea40 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e ed if no matchin
1ea50 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 g parameter is f
1ea60 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d ound. The param
1ea70 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 eter.** name mus
1ea80 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 t be given in UT
1ea90 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 F-8 even if the
1eaa0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
1eab0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 nt.** was prepar
1eac0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 ed from UTF-16 t
1ead0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ext using [sqlit
1eae0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1eaf0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c )]..**.** See al
1eb00 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
1eb10 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
1eb20 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
1eb30 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1eb40 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 er_count()], and
1eb50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
1eb60 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
1eb70 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 x()]..**.** Requ
1eb80 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
1eb90 33 36 34 31 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 3641].*/.SQLITE_
1eba0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
1ebb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
1ebc0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d ndex(sqlite3_stm
1ebd0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a t*, const char *
1ebe0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 zName);../*.** C
1ebf0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
1ec00 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 ll Bindings On A
1ec10 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
1ec20 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 ent {H13660} <S7
1ec30 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 0300>.**.** Cont
1ec40 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 rary to the intu
1ec50 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b ition of many, [
1ec60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
1ec70 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a does not reset.
1ec80 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
1ec90 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 bind_blob | bind
1eca0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 ings] on a [prep
1ecb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
1ecc0 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 .** Use this rou
1ecd0 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c tine to reset al
1ece0 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 l host parameter
1ecf0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a s to NULL..**.**
1ed00 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
1ed10 2a 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 53 51 * [H13661].*/.SQ
1ed20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1ed30 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 ite3_clear_bindi
1ed40 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
1ed50 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1ed60 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 REF: Number Of C
1ed70 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 olumns In A Resu
1ed80 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30 7d 20 lt Set {H13710}
1ed90 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 <S10700>.**.** R
1eda0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 eturn the number
1edb0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
1edc0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 he result set re
1edd0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
1ede0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1edf0 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 ment]. This rout
1ee00 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 ine returns 0 if
1ee10 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c pStmt is an SQL
1ee20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 .** statement th
1ee30 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 at does not retu
1ee40 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 rn data (for exa
1ee50 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d mple an [UPDATE]
1ee60 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 )..**.** Require
1ee70 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 31 ments:.** [H1371
1ee80 31 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 1].*/.SQLITE_API
1ee90 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c int sqlite3_col
1eea0 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 umn_count(sqlite
1eeb0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
1eec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1eed0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e Column Names In
1eee0 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 A Result Set {H
1eef0 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13720} <S10700>.
1ef00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1ef10 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
1ef20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f name assigned to
1ef30 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f a particular co
1ef40 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 lumn.** in the r
1ef50 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
1ef60 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
1ef70 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f t. The sqlite3_
1ef80 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a column_name().**
1ef90 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
1efa0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1efb0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
1efc0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a d UTF-8 string.*
1efd0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f * and sqlite3_co
1efe0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 lumn_name16() re
1eff0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1f000 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
1f010 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 ated.** UTF-16 s
1f020 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 tring. The firs
1f030 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
1f040 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
1f050 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 tement].** that
1f060 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b implements the [
1f070 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
1f080 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 t. The second pa
1f090 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
1f0a0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e * column number.
1f0b0 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 The leftmost c
1f0c0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 olumn is number
1f0d0 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 0..**.** The ret
1f0e0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 urned string poi
1f0f0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e nter is valid un
1f100 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b til either the [
1f110 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1f120 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f nt].** is destro
1f130 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f yed by [sqlite3_
1f140 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 finalize()] or u
1f150 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 ntil the next ca
1f160 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
1f170 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f _column_name() o
1f180 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
1f190 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 _name16() on the
1f1a0 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a same column..**
1f1b0 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d .** If sqlite3_m
1f1c0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 alloc() fails du
1f1d0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 ring the process
1f1e0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f ing of either ro
1f1f0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 utine.** (for ex
1f200 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 ample during a c
1f210 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 onversion from U
1f220 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 TF-8 to UTF-16)
1f230 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 then a.** NULL p
1f240 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
1f250 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 ed..**.** The na
1f260 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 me of a result c
1f270 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c olumn is the val
1f280 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 ue of the "AS" c
1f290 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 lause for.** tha
1f2a0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 t column, if the
1f2b0 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 re is an AS clau
1f2c0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 se. If there is
1f2d0 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a no AS clause.**
1f2e0 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f then the name o
1f2f0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 f the column is
1f300 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 unspecified and
1f310 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a may change from.
1f320 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f ** one release o
1f330 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 f SQLite to the
1f340 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 next..**.** Requ
1f350 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
1f360 33 37 32 31 5d 20 5b 48 31 33 37 32 33 5d 20 5b 3721] [H13723] [
1f370 48 31 33 37 32 34 5d 20 5b 48 31 33 37 32 35 5d H13724] [H13725]
1f380 20 5b 48 31 33 37 32 36 5d 20 5b 48 31 33 37 32 [H13726] [H1372
1f390 37 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 7].*/.SQLITE_API
1f3a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
1f3b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1f3c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1f3d0 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 int N);.SQLITE_A
1f3e0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 PI const void *s
1f3f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
1f400 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
1f410 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a t*, int N);../*.
1f420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 ** CAPI3REF: Sou
1f430 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 rce Of Data In A
1f440 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 Query Result {H
1f450 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13740} <S10700>.
1f460 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1f470 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d ines provide a m
1f480 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e eans to determin
1f490 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 e what column of
1f4a0 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 what.** table i
1f4b0 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 n which database
1f4c0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b a result of a [
1f4d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
1f4e0 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a t comes from..**
1f4f0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 The name of the
1f500 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 database or tab
1f510 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e le or column can
1f520 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a be returned as.
1f530 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d ** either a UTF-
1f540 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 8 or UTF-16 stri
1f550 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 ng. The _databa
1f560 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 se_ routines ret
1f570 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 urn.** the datab
1f580 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 ase name, the _t
1f590 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 able_ routines r
1f5a0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 eturn the table
1f5b0 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 name, and.** the
1f5c0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 origin_ routine
1f5d0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c s return the col
1f5e0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 umn name..** The
1f5f0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
1f600 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
1f610 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
1f620 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 atement] is dest
1f630 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b royed.** using [
1f640 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
1f650 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ()] or until the
1f660 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
1f670 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
1f680 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
1f690 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
1f6a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 .**.** The names
1f6b0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 returned are th
1f6c0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c e original un-al
1f6d0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 iased names of t
1f6e0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 he.** database,
1f6f0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d table, and colum
1f700 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 n..**.** The fir
1f710 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
1f720 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c he following cal
1f730 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 ls is a [prepare
1f740 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
1f750 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
1f760 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
1f770 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
1f780 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
1f790 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 d by.** the stat
1f7a0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 ement, where N i
1f7b0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e s the second fun
1f7c0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a ction argument..
1f7d0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 **.** If the Nth
1f7e0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 column returned
1f7f0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e by the statemen
1f800 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 t is an expressi
1f810 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 on or.** subquer
1f820 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 y and is not a c
1f830 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 olumn value, the
1f840 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 n all of these f
1f850 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a unctions return.
1f860 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 ** NULL. These
1f870 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c routine might al
1f880 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 so return NULL i
1f890 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
1f8a0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f ation error.** o
1f8b0 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 ccurs. Otherwis
1f8c0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 e, they return t
1f8d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 he name of the a
1f8e0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
1f8f0 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 , table.** and c
1f900 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 olumn that query
1f910 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 result column w
1f920 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f as extracted fro
1f930 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 m..**.** As with
1f940 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 all other SQLit
1f950 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f e APIs, those po
1f960 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36 stfixed with "16
1f970 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d " return.** UTF-
1f980 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 16 encoded strin
1f990 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 gs, the other fu
1f9a0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 nctions return U
1f9b0 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a TF-8. {END}.**.*
1f9c0 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 * These APIs are
1f9d0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
1f9e0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 if the library w
1f9f0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
1fa00 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
1fa10 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 ENABLE_COLUMN_ME
1fa20 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f TADATA] C-prepro
1fa30 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 cessor symbol de
1fa40 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 fined..**.** {A1
1fa50 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 3751}.** If two
1fa60 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 or more threads
1fa70 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 call one or more
1fa80 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
1fa90 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 es against the s
1faa0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 ame.** prepared
1fab0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f statement and co
1fac0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 lumn at the same
1fad0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 time then the r
1fae0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e esults are.** un
1faf0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 defined..**.** R
1fb00 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
1fb10 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 37 34 32 [H13741] [H13742
1fb20 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 31 33 37 ] [H13743] [H137
1fb30 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b 48 31 44] [H13745] [H1
1fb40 33 37 34 36 5d 20 5b 48 31 33 37 34 38 5d 0a 2a 3746] [H13748].*
1fb50 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d *.** If two or m
1fb60 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c ore threads call
1fb70 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
1fb80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
1fb90 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 database_name |
1fba0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 column metadata
1fbb0 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 interfaces].** f
1fbc0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 or the same [pre
1fbd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1fbe0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 and result colu
1fbf0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d mn.** at the sam
1fc00 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
1fc10 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
1fc20 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 fined..*/.SQLITE
1fc30 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
1fc40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
1fc50 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 database_name(sq
1fc60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
1fc70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
1fc80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
1fc90 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
1fca0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
1fcb0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
1fcc0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
1fcd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
1fce0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c n_table_name(sql
1fcf0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
1fd00 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
1fd10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
1fd20 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
1fd30 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
1fd40 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
1fd50 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
1fd60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 qlite3_column_or
1fd70 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 igin_name(sqlite
1fd80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 3_stmt*,int);.SQ
1fd90 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
1fda0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
1fdb0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 umn_origin_name1
1fdc0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
1fdd0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
1fde0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 I3REF: Declared
1fdf0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 Datatype Of A Qu
1fe00 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 ery Result {H137
1fe10 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 60} <S10700>.**.
1fe20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 ** The first par
1fe30 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 ameter is a [pre
1fe40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1fe50 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 ..** If this sta
1fe60 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c tement is a [SEL
1fe70 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 ECT] statement a
1fe80 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d nd the Nth colum
1fe90 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 n of the.** retu
1fea0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 rned result set
1feb0 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d of that [SELECT]
1fec0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 is a table colu
1fed0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 mn (not an.** ex
1fee0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
1fef0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 uery) then the d
1ff00 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 eclared type of
1ff10 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c the table.** col
1ff20 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e umn is returned.
1ff30 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c If the Nth col
1ff40 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c umn of the resul
1ff50 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 t set is an.** e
1ff60 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
1ff70 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 query, then a NU
1ff80 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
1ff90 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 turned..** The r
1ffa0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
1ffb0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 s always UTF-8 e
1ffc0 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a ncoded. {END}.**
1ffd0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c .** For example,
1ffe0 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 given the datab
1fff0 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a ase schema:.**.*
20000 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 * CREATE TABLE t
20010 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 1(c1 VARIANT);.*
20020 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c *.** and the fol
20030 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 lowing statement
20040 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a to be compiled:
20050 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 .**.** SELECT c1
20060 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 + 1, c1 FROM t1
20070 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ;.**.** this rou
20080 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 tine would retur
20090 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 n the string "VA
200a0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 RIANT" for the s
200b0 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 econd result.**
200c0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 column (i==1), a
200d0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nd a NULL pointe
200e0 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 r for the first
200f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 result column (i
20100 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ==0)..**.** SQLi
20110 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 te uses dynamic
20120 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e run-time typing.
20130 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 So just becaus
20140 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 e a column.** is
20150 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e declared to con
20160 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 tain a particula
20170 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 r type does not
20180 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a mean that the.**
20190 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 data stored in
201a0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f that column is o
201b0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 f the declared t
201c0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a ype. SQLite is.
201d0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 ** strongly type
201e0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e d, but the typin
201f0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 g is dynamic not
20200 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a static. Type.*
20210 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 * is associated
20220 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 with individual
20230 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 values, not with
20240 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a the containers.
20250 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 ** used to hold
20260 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a those values..**
20270 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
20280 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b 48 :.** [H13761] [H
20290 31 33 37 36 32 5d 20 5b 48 31 33 37 36 33 5d 0a 13762] [H13763].
202a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
202b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
202c0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
202d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
202e0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
202f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
20300 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c ite3_column_decl
20310 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 type16(sqlite3_s
20320 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
20330 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c * CAPI3REF: Eval
20340 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 uate An SQL Stat
20350 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c ement {H13200} <
20360 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 S10000>.**.** Af
20370 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 ter a [prepared
20380 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 statement] has b
20390 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 een prepared usi
203a0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 ng either.** [sq
203b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
203c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
203d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
203e0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 or one of the le
203f0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
20400 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 es [sqlite3_prep
20410 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 are()] or [sqlit
20420 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
20430 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a this function.*
20440 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 * must be called
20450 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
20460 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 es to evaluate t
20470 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a he statement..**
20480 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 .** The details
20490 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 of the behavior
204a0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 of the sqlite3_s
204b0 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 tep() interface
204c0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 depend.** on whe
204d0 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 ther the stateme
204e0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 nt was prepared
204f0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 using the newer
20500 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a "v2" interface.*
20510 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
20520 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
20530 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
20540 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 v2()] or the old
20550 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 er legacy.** int
20560 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f erface [sqlite3_
20570 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
20580 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
20590 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
205a0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 f the.** new "v2
205b0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
205c0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
205d0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
205e0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
205f0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
20600 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
20610 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
20620 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 In the legacy i
20630 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 nterface, the re
20640 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 turn value will
20650 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 be either [SQLIT
20660 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c E_BUSY],.** [SQL
20670 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 ITE_DONE], [SQLI
20680 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 TE_ROW], [SQLITE
20690 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c _ERROR], or [SQL
206a0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 ITE_MISUSE]..**
206b0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e With the "v2" in
206c0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 terface, any of
206d0 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c the other [resul
206e0 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b t codes] or.** [
206f0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
20700 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 codes] might be
20710 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c returned as well
20720 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
20730 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 BUSY] means that
20740 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
20750 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 gine was unable
20760 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a to acquire the.*
20770 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 * database locks
20780 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 it needs to do
20790 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 its job. If the
207a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
207b0 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f [COMMIT].** or o
207c0 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 ccurs outside of
207d0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
207e0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 nsaction, then y
207f0 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 ou can retry the
20800 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 .** statement.
20810 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 If the statement
20820 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 is not a [COMMI
20830 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 T] and occurs wi
20840 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 thin a.** explic
20850 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 it transaction t
20860 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 hen you should r
20870 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e ollback the tran
20880 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a saction before.*
20890 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a * continuing..**
208a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
208b0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
208c0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 statement has f
208d0 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
208e0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c g.** successfull
208f0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 y. sqlite3_step
20900 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
20910 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
20920 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a this virtual.**
20930 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 machine without
20940 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b first calling [
20950 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
20960 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 to reset the vi
20970 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
20980 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 back to its ini
20990 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a tial state..**.*
209a0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
209b0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 tement being exe
209c0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e cuted returns an
209d0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 y data, then [SQ
209e0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 LITE_ROW].** is
209f0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 returned each ti
20a00 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 me a new row of
20a10 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f data is ready fo
20a20 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 r processing by
20a30 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 the.** caller. T
20a40 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 he values may be
20a50 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 accessed using
20a60 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 the [column acce
20a70 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a ss functions]..*
20a80 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
20a90 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e is called again
20aa0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 to retrieve the
20ab0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 next row of dat
20ac0 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 a..**.** [SQLITE
20ad0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 _ERROR] means th
20ae0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 at a run-time er
20af0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 ror (such as a c
20b00 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f onstraint.** vio
20b10 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 lation) has occu
20b20 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 rred. sqlite3_s
20b30 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 tep() should not
20b40 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e be called again
20b50 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d on.** the VM. M
20b60 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ore information
20b70 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 may be found by
20b80 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
20b90 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 _errmsg()]..** W
20ba0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 ith the legacy i
20bb0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 nterface, a more
20bc0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
20bd0 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c code (for exampl
20be0 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e e,.** [SQLITE_IN
20bf0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 TERRUPT], [SQLIT
20c00 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 E_SCHEMA], [SQLI
20c10 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 TE_CORRUPT], and
20c20 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 so forth).** ca
20c30 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 n be obtained by
20c40 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
20c50 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 3_reset()] on th
20c60 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
20c70 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 tatement]. In t
20c80 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
20c90 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 e,.** the more s
20ca0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
20cb0 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 de is returned d
20cc0 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 irectly by sqlit
20cd0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a e3_step()..**.**
20ce0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
20cf0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
20d00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 this routine was
20d10 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 called inapprop
20d20 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 riately..** Perh
20d30 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 aps it was calle
20d40 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 d on a [prepared
20d50 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
20d60 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 has.** already
20d70 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 been [sqlite3_fi
20d80 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a nalize | finaliz
20d90 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 ed] or on one th
20da0 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f at had.** previo
20db0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 usly returned [S
20dc0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 QLITE_ERROR] or
20dd0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
20de0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 Or it could.** b
20df0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 e the case that
20e00 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
20e10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
20e20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 being used by tw
20e30 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 o or.** more thr
20e40 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
20e50 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e moment in time.
20e60 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 .**.** <b>Goofy
20e70 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a Interface Alert:
20e80 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 </b> In the lega
20e90 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 cy interface, th
20ea0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
20eb0 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 .** API always r
20ec0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 eturns a generic
20ed0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 error code, [SQ
20ee0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c LITE_ERROR], fol
20ef0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 lowing any.** er
20f00 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ror other than [
20f10 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 SQLITE_BUSY] and
20f20 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
20f30 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c . You must call
20f40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
20f50 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
20f60 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 3_finalize()] in
20f70 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f order to find o
20f80 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 ne of the.** spe
20f90 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
20fa0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 es] that better
20fb0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
20fc0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 ror..** We admit
20fd0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 that this is a
20fe0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 goofy design. T
20ff0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 he problem has b
21000 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 een fixed.** wit
21010 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
21020 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 face. If you pr
21030 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 epare all of you
21040 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 r SQL statements
21050 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 .** using either
21060 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
21070 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
21080 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
21090 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f ()] instead.** o
210a0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 f the legacy [sq
210b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
210c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
210d0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 epare16()] inter
210e0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 faces,.** then t
210f0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
21100 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 [error codes] a
21110 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 re returned dire
21120 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 ctly.** by sqlit
21130 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 e3_step(). The
21140 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 use of the "v2"
21150 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 interface is rec
21160 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 ommended..**.**
21170 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
21180 20 5b 48 31 33 32 30 32 5d 20 5b 48 31 35 33 30 [H13202] [H1530
21190 34 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48 31 35 4] [H15306] [H15
211a0 33 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a 2a 2f 308] [H15310].*/
211b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
211c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c sqlite3_step(sql
211d0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
211e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
211f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
21200 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 in a result set
21210 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 {H13770} <S10700
21220 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 >.**.** Returns
21230 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 the number of va
21240 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 lues in the curr
21250 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 ent row of the r
21260 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a esult set..**.**
21270 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
21280 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 33 37 * [H13771] [H137
21290 37 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 72].*/.SQLITE_AP
212a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 I int sqlite3_da
212b0 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 ta_count(sqlite3
212c0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
212d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
212e0 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 Fundamental Data
212f0 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d 20 3c types {H10265} <
21300 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30 3e 0a S10110><S10120>.
21310 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c ** KEYWORDS: SQL
21320 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b ITE_TEXT.**.** {
21330 48 31 30 32 36 36 7d 20 45 76 65 72 79 20 76 61 H10266} Every va
21340 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 lue in SQLite ha
21350 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 s one of five fu
21360 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 ndamental dataty
21370 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a pes:.**.** <ul>.
21380 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 ** <li> 64-bit s
21390 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
213a0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 <li> 64-bit IEE
213b0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 E floating point
213c0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 number.** <li>
213d0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 string.** <li> B
213e0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c LOB.** <li> NULL
213f0 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a .** </ul> {END}.
21400 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
21410 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 tants are codes
21420 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 for each of thos
21430 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e e types..**.** N
21440 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ote that the SQL
21450 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e ITE_TEXT constan
21460 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 t was also used
21470 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f in SQLite versio
21480 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d n 2.** for a com
21490 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e pletely differen
214a0 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 t meaning. Soft
214b0 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 ware that links
214c0 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 against both.**
214d0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 SQLite version 2
214e0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 and SQLite vers
214f0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 ion 3 should use
21500 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e SQLITE3_TEXT, n
21510 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 ot.** SQLITE_TEX
21520 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 T..*/.#define SQ
21530 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a LITE_INTEGER 1.
21540 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
21550 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e LOAT 2.#defin
21560 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 e SQLITE_BLOB
21570 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
21580 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 TE_NULL 5.#i
21590 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 fdef SQLITE_TEXT
215a0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
215b0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 TEXT.#else.# def
215c0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 ine SQLITE_TEXT
215d0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 3.#endif.#de
215e0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 fine SQLITE3_TEX
215f0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 T 3../*.** C
21600 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
21610 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 Values From A Qu
21620 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c 53 31 ery {H13800} <S1
21630 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0700>.** KEYWORD
21640 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 S: {column acces
21650 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a s functions}.**.
21660 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
21670 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 s form the "resu
21680 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e lt set query" in
21690 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 terface..**.** T
216a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
216b0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
216c0 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 about a single
216d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 column of the cu
216e0 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 rrent.** result
216f0 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 row of a query.
21700 20 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 In every case t
21710 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
21720 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
21730 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
21740 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
21750 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
21760 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
21770 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
21780 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
21790 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
217a0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
217b0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
217c0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
217d0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
217e0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
217f0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
21800 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
21810 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
21820 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 urned. The left
21830 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
21840 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
21850 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
21860 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * The number of
21870 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
21880 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 esult can be det
21890 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a ermined using.**
218a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
218b0 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a _count()]..**.**
218c0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 If the SQL stat
218d0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
218e0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 urrently point t
218f0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f o a valid row, o
21900 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 r if the.** colu
21910 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 mn index is out
21920 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 of range, the re
21930 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 sult is undefine
21940 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 d..** These rout
21950 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 ines may only be
21960 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 called when the
21970 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
21980 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
21990 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 _step()] has ret
219a0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f urned [SQLITE_RO
219b0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a W] and neither.*
219c0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
219d0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 ()] nor [sqlite3
219e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 _finalize()] hav
219f0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 e been called su
21a00 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 bsequently..** I
21a10 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 f any of these r
21a20 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
21a30 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 ed after [sqlite
21a40 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
21a50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
21a60 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b ze()] or after [
21a70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
21a80 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 has returned.**
21a90 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 something other
21aa0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 than [SQLITE_ROW
21ab0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 ], the results a
21ac0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a re undefined..**
21ad0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 If [sqlite3_ste
21ae0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 p()] or [sqlite3
21af0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
21b00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
21b10 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 ].** are called
21b20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 from a different
21b30 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e thread while an
21b40 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
21b50 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 nes.** are pendi
21b60 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 ng, then the res
21b70 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
21b80 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
21b90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
21ba0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
21bb0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 rns the.** [SQLI
21bc0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
21bd0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 atype code] for
21be0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 the initial data
21bf0 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 type.** of the
21c00 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 result column.
21c10 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c The returned val
21c20 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 ue is one of [SQ
21c30 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a LITE_INTEGER],.*
21c40 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d * [SQLITE_FLOAT]
21c50 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c , [SQLITE_TEXT],
21c60 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 [SQLITE_BLOB],
21c70 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d or [SQLITE_NULL]
21c80 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 . The value.**
21c90 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
21ca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
21cb0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e ) is only meanin
21cc0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a gful if no type.
21cd0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 ** conversions h
21ce0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 ave occurred as
21cf0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e described below.
21d00 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 After a type c
21d10 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 onversion,.** th
21d20 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
21d30 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
21d40 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 mn_type() is und
21d50 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a efined. Future.
21d60 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 ** versions of S
21d70 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 QLite may change
21d80 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
21d90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
21da0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 type().** follow
21db0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 ing a type conve
21dc0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 rsion..**.** If
21dd0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
21de0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 BLOB or UTF-8 st
21df0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 ring then the sq
21e00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
21e10 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 es().** routine
21e20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
21e30 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
21e40 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
21e50 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 ng..** If the re
21e60 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 sult is a UTF-16
21e70 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 string, then sq
21e80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
21e90 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a es() converts.**
21ea0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 the string to U
21eb0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 TF-8 and then re
21ec0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
21ed0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 of bytes..** If
21ee0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
21ef0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 numeric value t
21f00 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
21f10 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a mn_bytes() uses.
21f20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 ** [sqlite3_snpr
21f30 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 intf()] to conve
21f40 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f rt that value to
21f50 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 a UTF-8 string
21f60 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 and returns.** t
21f70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
21f80 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e es in that strin
21f90 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 g..** The value
21fa0 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f returned does no
21fb0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 t include the ze
21fc0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 ro terminator at
21fd0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 the end.** of t
21fe0 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 he string. For
21ff0 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c clarity: the val
22000 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 ue returned is t
22010 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
22020 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 bytes in the str
22030 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d ing, not the num
22040 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
22050 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 s..**.** Strings
22060 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
22070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
22080 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
22090 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a olumn_text16(),.
220a0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 ** even empty st
220b0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 rings, are alway
220c0 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 s zero terminate
220d0 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a d. The return.*
220e0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c * value from sql
220f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
22100 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 () for a zero-le
22110 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 ngth BLOB is an
22120 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 arbitrary.** poi
22130 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 nter, possibly e
22140 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ven a NULL point
22150 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 er..**.** The sq
22160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
22170 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 es16() routine i
22180 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c s similar to sql
22190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
221a0 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 s().** but leave
221b0 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 s the result in
221c0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 UTF-16 in native
221d0 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 byte order inst
221e0 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a ead of UTF-8..**
221f0 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e The zero termin
22200 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c ator is not incl
22210 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 uded in this cou
22220 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 nt..**.** The ob
22230 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
22240 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
22250 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a _value()] is an.
22260 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 ** [unprotected
22270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
22280 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f bject. An unpro
22290 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
222a0 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d alue object.** m
222b0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
222c0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 with [sqlite3_bi
222d0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 nd_value()] and
222e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
222f0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 value()]..** If
22300 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 the [unprotected
22310 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
22320 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
22330 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
22340 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
22350 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 s used in any ot
22360 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 her way, includi
22370 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 ng calls.** to r
22380 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
22390 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
223a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
223b0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
223c0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
223d0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 _bytes()], then
223e0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
223f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
22400 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
22410 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 attempt to conve
22420 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 rt the value whe
22430 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 re appropriate.
22440 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c For.** example,
22450 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c if the internal
22460 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
22470 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 is FLOAT and a t
22480 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ext result.** is
22490 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c requested, [sql
224a0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
224b0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
224c0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 lly to perform t
224d0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e he.** conversion
224e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
224f0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 The following t
22500 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 able details the
22510 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 conversions.**
22520 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 that are applied
22530 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
22540 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 ote>.** <table b
22550 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 order="1">.** <t
22560 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c r><th> Internal<
22570 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 br>Type <th> Req
22580 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c uested<br>Type <
22590 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a th> Conversion.
225a0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 **.** <tr><td>
225b0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 NULL <td> INT
225c0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 EGER <td> Resu
225d0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c lt is 0.** <tr><
225e0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
225f0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
22600 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a Result is 0.0.*
22610 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
22620 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
22630 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
22640 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
22650 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
22660 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
22670 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
22680 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
22690 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
226a0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 ER <td> FLOAT
226b0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
226c0 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 from integer to
226d0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
226e0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
226f0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
22700 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
22710 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a f the integer.**
22720 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
22730 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 R <td> BLOB
22740 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 <td> Same as I
22750 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 NTEGER->TEXT.**
22760 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
22770 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
22780 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
22790 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 om float to inte
227a0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ger.** <tr><td>
227b0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
227c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
227d0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
227e0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 the float.** <tr
227f0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
22800 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
22810 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 d> Same as FLOAT
22820 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
22830 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
22840 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
22850 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 Use atoi().** <t
22860 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
22870 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
22880 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a td> Use atof().*
22890 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
228a0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
228b0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 <td> No chang
228c0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 e.** <tr><td> B
228d0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOB <td> INTE
228e0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 GER <td> Conve
228f0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 rt to TEXT then
22900 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 use atoi().** <t
22910 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
22920 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
22930 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 td> Convert to T
22940 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f EXT then use ato
22950 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 f().** <tr><td>
22960 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 BLOB <td>
22970 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 TEXT <td> Add
22980 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 a zero terminat
22990 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 or if needed.**
229a0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c </table>.** </bl
229b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
229c0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 The table above
229d0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 makes reference
229e0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 to standard C li
229f0 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 brary functions
22a00 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 atoi().** and at
22a10 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f of(). SQLite do
22a20 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 es not really us
22a30 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e e these function
22a40 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a s. It has its.*
22a50 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 * own equivalent
22a60 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e internal routin
22a70 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 es. The atoi()
22a80 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 and atof() names
22a90 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 are.** used in
22aa0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 the table for br
22ab0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 evity and becaus
22ac0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c e they are famil
22ad0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 iar to most.** C
22ae0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a programmers..**
22af0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 .** Note that wh
22b00 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 en type conversi
22b10 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 ons occur, point
22b20 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ers returned by
22b30 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 prior.** calls t
22b40 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
22b50 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
22b60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 _column_text(),
22b70 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 and/or.** sqlite
22b80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
22b90 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 ) may be invalid
22ba0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f ated..** Type co
22bb0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f nversions and po
22bc0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 inter invalidati
22bd0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a ons might occur.
22be0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 ** in the follow
22bf0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a ing cases:.**.**
22c00 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 <ul>.** <li> Th
22c10 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
22c20 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 t is a BLOB and
22c30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
22c40 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 ext() or.**
22c50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
22c60 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
22c70 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d ed. A zero-term
22c80 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 inator might.**
22c90 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 need to be
22ca0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 added to the str
22cb0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 ing.</li>.** <li
22cc0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
22cd0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 ntent is UTF-8 t
22ce0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
22cf0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
22d00 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
22d10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
22d20 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
22d30 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
22d40 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
22d50 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e to UTF-16.
22d60 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
22d70 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
22d80 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 t is UTF-16 text
22d90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
22da0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
22db0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
22dc0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 olumn_text() is
22dd0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
22de0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
22df0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 verted.** t
22e00 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a o UTF-8.</li>.**
22e10 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e </ul>.**.** Con
22e20 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e versions between
22e30 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 UTF-16be and UT
22e40 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 F-16le are alway
22e50 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 s done in place
22e60 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e and do.** not in
22e70 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 validate a prior
22e80 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 pointer, though
22e90 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 of course the c
22ea0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 ontent of the bu
22eb0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 ffer.** that the
22ec0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 prior pointer p
22ed0 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 oints to will ha
22ee0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 ve been modified
22ef0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a . Other kinds.*
22f00 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 * of conversion
22f10 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 are done in plac
22f20 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 e when it is pos
22f30 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 sible, but somet
22f40 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 imes they.** are
22f50 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e not possible an
22f60 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 d in those cases
22f70 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 prior pointers
22f80 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e are invalidated.
22f90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 .**.** The safes
22fa0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f t and easiest to
22fb0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 remember policy
22fc0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 is to invoke th
22fd0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
22fe0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f in one of the fo
22ff0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a llowing ways:.**
23000 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 .** <ul>.** <li
23010 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
23020 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 text() followed
23030 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
23040 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
23050 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
23060 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c olumn_blob() fol
23070 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
23080 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
23090 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
230a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
230b0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 16() followed by
230c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
230d0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a bytes16()</li>.*
230e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
230f0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f other words, yo
23100 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 u should call sq
23110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
23120 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t(),.** sqlite3_
23130 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f column_blob(), o
23140 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
23150 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 _text16() first
23160 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 to force the res
23170 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ult.** into the
23180 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 desired format,
23190 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 then invoke sqli
231a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
231b0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
231c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
231d0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 ) to find the si
231e0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ze of the result
231f0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 . Do not mix ca
23200 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 lls.** to sqlite
23210 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
23220 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
23230 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 n_blob() with ca
23240 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
23250 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
23260 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d (), and do not m
23270 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ix calls to sqli
23280 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
23290 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 6().** with call
232a0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
232b0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a umn_bytes()..**.
232c0 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 ** The pointers
232d0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
232e0 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
232f0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
23300 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
23310 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
23320 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
23330 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
23340 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
23350 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
23360 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 )] is called. T
23370 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 he memory space
23380 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 used to hold str
23390 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 ings.** and BLOB
233a0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d s is freed autom
233b0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 atically. Do <b
233c0 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 >not</b> pass th
233d0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
233e0 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ned.** [sqlite3_
233f0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 column_blob()],
23400 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
23410 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e text()], etc. in
23420 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
23430 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ree()]..**.** If
23440 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
23450 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 tion error occur
23460 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 s during the eva
23470 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a luation of any.*
23480 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 * of these routi
23490 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 nes, a default v
234a0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 alue is returned
234b0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 . The default v
234c0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 alue.** is eithe
234d0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c r the integer 0,
234e0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f the floating po
234f0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 int number 0.0,
23500 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 or a NULL.** poi
23510 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e nter. Subsequen
23520 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 t calls to [sqli
23530 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 te3_errcode()] w
23540 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 ill return.** [S
23550 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a QLITE_NOMEM]..**
23560 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
23570 3a 0a 2a 2a 20 5b 48 31 33 38 30 33 5d 20 5b 48 :.** [H13803] [H
23580 31 33 38 30 36 5d 20 5b 48 31 33 38 30 39 5d 20 13806] [H13809]
23590 5b 48 31 33 38 31 32 5d 20 5b 48 31 33 38 31 35 [H13812] [H13815
235a0 5d 20 5b 48 31 33 38 31 38 5d 20 5b 48 31 33 38 ] [H13818] [H138
235b0 32 31 5d 20 5b 48 31 33 38 32 34 5d 0a 2a 2a 20 21] [H13824].**
235c0 5b 48 31 33 38 32 37 5d 20 5b 48 31 33 38 33 30 [H13827] [H13830
235d0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
235e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
235f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
23600 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
23610 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
23620 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
23630 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 _column_bytes(sq
23640 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
23650 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
23660 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
23670 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 olumn_bytes16(sq
23680 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
23690 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
236a0 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 PI double sqlite
236b0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 3_column_double(
236c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
236d0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
236e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
236f0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 _column_int(sqli
23700 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
23710 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
23720 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
23730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
23740 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
23750 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
23760 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 LITE_API const u
23770 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 nsigned char *sq
23780 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
23790 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
237a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
237b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
237c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
237d0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 n_text16(sqlite3
237e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
237f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
23800 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
23810 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 _type(sqlite3_st
23820 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
23830 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
23840 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 e3_value *sqlite
23850 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 3_column_value(s
23860 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
23870 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t iCol);../*.**
23880 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f CAPI3REF: Destro
23890 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 y A Prepared Sta
238a0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 tement Object {H
238b0 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 13300} <S70300><
238c0 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30100>.**.** Th
238d0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 e sqlite3_finali
238e0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 ze() function is
238f0 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 called to delet
23900 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 e a [prepared st
23910 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 atement]..** If
23920 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 the statement wa
23930 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 s executed succe
23940 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 ssfully or not e
23950 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 xecuted at all,
23960 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f then.** SQLITE_O
23970 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 K is returned. I
23980 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 f execution of t
23990 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 he statement fai
239a0 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b led then an.** [
239b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b error code] or [
239c0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
239d0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
239e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
239f0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c tine can be call
23a00 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 ed at any point
23a10 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 during the execu
23a20 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b tion of the.** [
23a30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
23a40 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 nt]. If the vir
23a50 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 tual machine has
23a60 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 not.** complete
23a70 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e d execution when
23a80 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
23a90 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 called, that is
23aa0 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 like.** encount
23ab0 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f ering an error o
23ac0 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e r an [sqlite3_in
23ad0 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 terrupt | interr
23ae0 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c upt]..** Incompl
23af0 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 ete updates may
23b00 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 be rolled back a
23b10 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 nd transactions
23b20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 canceled,.** dep
23b30 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 ending on the ci
23b40 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 rcumstances, and
23b50 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 the.** [error c
23b60 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 ode] returned wi
23b70 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 ll be [SQLITE_AB
23b80 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ORT]..**.** Requ
23b90 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
23ba0 31 33 30 32 5d 20 5b 48 31 31 33 30 34 5d 0a 2a 1302] [H11304].*
23bb0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
23bc0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
23bd0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a e(sqlite3_stmt *
23be0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
23bf0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
23c00 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
23c10 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 ent Object {H133
23c20 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 30} <S70300>.**.
23c30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
23c40 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 eset() function
23c50 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 is called to res
23c60 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 et a [prepared s
23c70 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a tatement].** obj
23c80 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 ect back to its
23c90 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 initial state, r
23ca0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 eady to be re-ex
23cb0 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 ecuted..** Any S
23cc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 QL statement var
23cd0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 iables that had
23ce0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 values bound to
23cf0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 them using.** th
23d00 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
23d10 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 blob | sqlite3_b
23d20 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 ind_*() API] ret
23d30 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 ain their values
23d40 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 ..** Use [sqlite
23d50 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
23d60 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 ()] to reset the
23d70 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a bindings..**.**
23d80 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 {H11332} The [s
23d90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
23da0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 interface reset
23db0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
23dc0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 statement] S.**
23dd0 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f back to
23de0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
23df0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a f its program..*
23e00 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 *.** {H11334} If
23e10 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
23e20 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
23e30 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 3_step(S)] for t
23e40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
23e50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
23e60 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
23e70 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
23e80 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
23e90 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 or if
23ea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
23eb0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f ] has never befo
23ec0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f re been called o
23ed0 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 n S,.**
23ee0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 then [sqlite3_r
23ef0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 eset(S)] returns
23f00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
23f10 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 .** {H11336} If
23f20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
23f30 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
23f40 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 _step(S)] for th
23f50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
23f60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
23f70 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 t] S indicated a
23f80 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a n error, then.**
23f90 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
23fa0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 e3_reset(S)] ret
23fb0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 urns an appropri
23fc0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
23fd0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d ..**.** {H11338}
23fe0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
23ff0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
24000 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 e does not chang
24010 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 e the values.**
24020 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 of any
24030 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
24040 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 ob|bindings] on
24050 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
24060 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 atement] S..*/.S
24070 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
24080 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 lite3_reset(sqli
24090 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
240a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
240b0 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 F: Create Or Red
240c0 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 efine SQL Functi
240d0 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 ons {H16100} <S2
240e0 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0200>.** KEYWORD
240f0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 S: {function cre
24100 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a ation routines}.
24110 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
24120 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
24130 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a d SQL function}.
24140 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
24150 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
24160 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d d SQL functions}
24170 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f .**.** These two
24180 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c functions (coll
24190 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 ectively known a
241a0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 s "function crea
241b0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a tion routines").
241c0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 ** are used to a
241d0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 dd SQL functions
241e0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f or aggregates o
241f0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 r to redefine th
24200 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 e behavior.** of
24210 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 existing SQL fu
24220 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 nctions or aggre
24230 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 gates. The only
24240 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 difference betw
24250 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 een the.** two i
24260 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e s that the secon
24270 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 d parameter, the
24280 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 name of the (sc
24290 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f alar) function o
242a0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 r.** aggregate,
242b0 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 is encoded in UT
242c0 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f F-8 for sqlite3_
242d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
242e0 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 ) and UTF-16.**
242f0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
24300 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e te_function16().
24310 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
24320 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
24330 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
24340 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 ection] to which
24350 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 the SQL.** func
24360 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 tion is to be ad
24370 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c ded. If a singl
24380 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d e program uses m
24390 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 ore than one dat
243a0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
243b0 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 ion internally,
243c0 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f then SQL functio
243d0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 ns must be added
243e0 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f individually to
243f0 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 .** each databas
24400 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a e connection..**
24410 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 .** The second p
24420 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
24430 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 name of the SQL
24440 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 function to be c
24450 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 reated or.** red
24460 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e efined. The len
24470 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 gth of the name
24480 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 is limited to 25
24490 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 5 bytes, exclusi
244a0 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 ve of.** the zer
244b0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e o-terminator. N
244c0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d ote that the nam
244d0 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 e length limit i
244e0 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a s in bytes, not.
244f0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 ** characters.
24500 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 Any attempt to c
24510 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e reate a function
24520 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e with a longer n
24530 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 ame.** will resu
24540 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 lt in [SQLITE_ER
24550 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 ROR] being retur
24560 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ned..**.** The t
24570 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 hird parameter (
24580 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 nArg).** is the
24590 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
245a0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c nts that the SQL
245b0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
245c0 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e aggregate takes.
245d0 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 If this paramet
245e0 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 er is -1, then t
245f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
24600 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 or.** aggregate
24610 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d may take any num
24620 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
24630 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 between 0 and t
24640 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 he limit.** set
24650 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 by [sqlite3_limi
24660 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 t]([SQLITE_LIMIT
24670 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e _FUNCTION_ARG]).
24680 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a If the third.*
24690 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c * parameter is l
246a0 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 ess than -1 or g
246b0 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 reater than 127
246c0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
246d0 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 r is.** undefine
246e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 d..**.** The fou
246f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 rth parameter, e
24700 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 TextRep, specifi
24710 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 es what.** [SQLI
24720 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 TE_UTF8 | text e
24730 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 ncoding] this SQ
24740 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 L function prefe
24750 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 rs for.** its pa
24760 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 rameters. Any S
24770 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c QL function impl
24780 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c ementation shoul
24790 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 d be able to wor
247a0 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 k.** work with U
247b0 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 TF-8, UTF-16le,
247c0 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 or UTF-16be. Bu
247d0 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 t some implement
247e0 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a ations may be.**
247f0 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 more efficient
24800 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e with one encodin
24810 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 g than another.
24820 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 An application
24830 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 may.** invoke sq
24840 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
24850 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 ction() or sqlit
24860 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
24870 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a on16() multiple.
24880 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 ** times with th
24890 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
248a0 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 but with differe
248b0 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 nt values of eTe
248c0 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d xtRep..** When m
248d0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
248e0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 tations of the s
248f0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 ame function are
24900 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 available, SQLi
24910 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 te.** will pick
24920 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 the one that inv
24930 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 olves the least
24940 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 amount of data c
24950 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 onversion..** If
24960 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 there is only a
24970 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e single implemen
24980 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 tation which doe
24990 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 s not care what
249a0 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 text.** encoding
249b0 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 is used, then t
249c0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
249d0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 nt should be [SQ
249e0 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a LITE_ANY]..**.**
249f0 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d The fifth param
24a00 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 eter is an arbit
24a10 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 rary pointer. T
24a20 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
24a30 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 n of the.** func
24a40 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 tion can gain ac
24a50 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 cess to this poi
24a60 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 nter using [sqli
24a70 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
24a80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 ..**.** The seve
24a90 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 nth, eighth and
24aa0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 ninth parameters
24ab0 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 , xFunc, xStep a
24ac0 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a nd xFinal, are.*
24ad0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d * pointers to C-
24ae0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f language functio
24af0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ns that implemen
24b00 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
24b10 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
24b20 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c te. A scalar SQL
24b30 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
24b40 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 es an implementa
24b50 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e tion of the xFun
24b60 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e c.** callback on
24b70 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 ly, NULL pointer
24b80 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 s should be pass
24b90 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 ed as the xStep
24ba0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 and xFinal.** pa
24bb0 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 rameters. An agg
24bc0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
24bd0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
24be0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
24bf0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 f xStep.** and x
24c00 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 Final and NULL s
24c10 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 hould be passed
24c20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 for xFunc. To de
24c30 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 lete an existing
24c40 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e .** SQL function
24c50 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 or aggregate, p
24c60 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c ass NULL for all
24c70 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 three function
24c80 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a callbacks..**.**
24c90 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 It is permitted
24ca0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c to register mul
24cb0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
24cc0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
24cd0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 e.** functions w
24ce0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ith the same nam
24cf0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 e but with eithe
24d00 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 r differing numb
24d10 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 ers of.** argume
24d20 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 nts or differing
24d30 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
24d40 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 encodings. SQLi
24d50 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 te will use.** t
24d60 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
24d70 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 n that most clos
24d80 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 ely matches the
24d90 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 way in which the
24da0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e .** SQL function
24db0 20 69 73 20 75 73 65 64 2e 20 20 41 20 66 75 6e is used. A fun
24dc0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
24dd0 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d tion with a non-
24de0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 negative.** nArg
24df0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
24e00 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 better match tha
24e10 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 n a function imp
24e20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 lementation with
24e30 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e .** a negative n
24e40 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e Arg. A function
24e50 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 where the prefe
24e60 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
24e70 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 ng.** matches th
24e80 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 e database encod
24e90 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a ing is a better.
24ea0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 ** match than a
24eb0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
24ec0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 he encoding is d
24ed0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 ifferent. .** A
24ee0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
24ef0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 the encoding dif
24f00 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 ference is betwe
24f10 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 en UTF16le and U
24f20 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 TF16be.** is a c
24f30 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e loser match than
24f40 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 a function wher
24f50 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 e the encoding d
24f60 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 ifference is.**
24f70 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 between UTF8 and
24f80 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 UTF16..**.** Bu
24f90 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 ilt-in functions
24fa0 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 may be overload
24fb0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 ed by new applic
24fc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
24fd0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 nctions..** The
24fe0 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f first applicatio
24ff0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
25000 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 on with a given
25010 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 name overrides a
25020 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 ll.** built-in f
25030 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 unctions in the
25040 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
25050 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 onnection] with
25060 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a the same name..*
25070 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 * Subsequent app
25080 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
25090 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 functions of th
250a0 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 e same name only
250b0 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 override .** pr
250c0 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d ior application-
250d0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
250e0 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 s that are an ex
250f0 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 act match for th
25100 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 e.** number of p
25110 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 arameters and pr
25120 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 eferred encoding
25130 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 ..**.** An appli
25140 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
25150 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 unction is permi
25160 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 tted to call oth
25170 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 er.** SQLite int
25180 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 erfaces. Howeve
25190 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 r, such calls mu
251a0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 st not.** close
251b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
251c0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 nection nor fina
251d0 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 lize or reset th
251e0 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 e prepared.** st
251f0 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 atement in which
25200 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 the function is
25210 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 running..**.**
25220 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
25230 20 5b 48 31 36 31 30 33 5d 20 5b 48 31 36 31 30 [H16103] [H1610
25240 36 5d 20 5b 48 31 36 31 30 39 5d 20 5b 48 31 36 6] [H16109] [H16
25250 31 31 32 5d 20 5b 48 31 36 31 31 38 5d 20 5b 48 112] [H16118] [H
25260 31 36 31 32 31 5d 20 5b 48 31 36 31 32 37 5d 0a 16121] [H16127].
25270 2a 2a 20 5b 48 31 36 31 33 30 5d 20 5b 48 31 36 ** [H16130] [H16
25280 31 33 33 5d 20 5b 48 31 36 31 33 36 5d 20 5b 48 133] [H16136] [H
25290 31 36 31 33 39 5d 20 5b 48 31 36 31 34 32 5d 0a 16139] [H16142].
252a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
252b0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
252c0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c _function(. sql
252d0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
252e0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
252f0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
25300 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
25310 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
25320 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
25330 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
25340 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
25350 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
25360 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
25370 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
25380 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
25390 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
253a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
253b0 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ).);.SQLITE_API
253c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
253d0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 te_function16(.
253e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
253f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e const void *zFun
25400 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
25410 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
25420 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
25430 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
25440 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
25450 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
25460 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
25470 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
25480 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
25490 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
254a0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
254b0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
254c0 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ext*).);../*.**
254d0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 CAPI3REF: Text E
254e0 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37 ncodings {H10267
254f0 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31 } <S50200> <H161
25500 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
25510 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 constant define
25520 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 integer codes th
25530 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 at represent the
25540 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 various.** text
25550 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f encodings suppo
25560 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a rted by SQLite..
25570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
25580 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 E_UTF8
25590 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
255a0 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 E_UTF16LE
255b0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
255c0 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 E_UTF16BE
255d0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
255e0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 E_UTF16
255f0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 4 /* Use nat
25600 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a ive byte order *
25610 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
25620 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 _ANY
25630 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
25640 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 create_function
25650 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
25660 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
25670 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 GNED 8 /* sq
25680 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
25690 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a lation only */..
256a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
256b0 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 Deprecated Funct
256c0 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 ions.** DEPRECAT
256d0 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 ED.**.** These f
256e0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 unctions are [de
256f0 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f precated]. In o
25700 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e rder to maintain
25710 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f .** backwards co
25720 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 mpatibility with
25730 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 older code, the
25740 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e se functions con
25750 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 tinue .** to be
25760 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 supported. Howe
25770 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 ver, new applica
25780 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f tions should avo
25790 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 id.** the use of
257a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
257b0 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 . To help encou
257c0 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 rage people to a
257d0 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 void.** using th
257e0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 ese functions, w
257f0 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 e are not going
25800 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 to tell you what
25810 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 they do..*/.#if
25820 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 ndef SQLITE_OMIT
25830 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 _DEPRECATED.SQLI
25840 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
25850 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
25860 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
25870 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e ount(sqlite3_con
25880 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 text*);.SQLITE_A
25890 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
258a0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
258b0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 _expired(sqlite3
258c0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f _stmt*);.SQLITE_
258d0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
258e0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
258f0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 3_transfer_bindi
25900 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
25910 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a *, sqlite3_stmt*
25920 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
25930 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
25940 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 int sqlite3_glob
25950 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 al_recover(void)
25960 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
25970 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 ITE_DEPRECATED v
25980 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 oid sqlite3_thre
25990 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 ad_cleanup(void)
259a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
259b0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
259c0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 nt sqlite3_memor
259d0 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 y_alarm(void(*)(
259e0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e void*,sqlite3_in
259f0 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 t64,int),void*,s
25a00 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 qlite3_int64);.#
25a10 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
25a20 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 I3REF: Obtaining
25a30 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 SQL Function Pa
25a40 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b rameter Values {
25a50 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e H15100} <S20200>
25a60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e .**.** The C-lan
25a70 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 guage implementa
25a80 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 tion of SQL func
25a90 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 tions and aggreg
25aa0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 ates uses.** thi
25ab0 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 s set of interfa
25ac0 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 ce routines to a
25ad0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 ccess the parame
25ae0 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a ter values on.**
25af0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 the function or
25b00 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a aggregate..**.*
25b10 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 * The xFunc (for
25b20 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e scalar function
25b30 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 s) or xStep (for
25b40 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 aggregates) par
25b50 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 ameters.** to [s
25b60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
25b70 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 nction()] and [s
25b80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
25b90 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 nction16()].** d
25ba0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 efine callbacks
25bb0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 that implement t
25bc0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 he SQL functions
25bd0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e and aggregates.
25be0 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 .** The 4th para
25bf0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 meter to these c
25c00 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 allbacks is an a
25c10 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
25c20 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 to.** [protecte
25c30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
25c40 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 objects. There
25c50 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 is one [sqlite3
25c60 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 _value] object f
25c70 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d or.** each param
25c80 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 eter to the SQL
25c90 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 function. These
25ca0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
25cb0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 ed to.** extract
25cc0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 values from the
25cd0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
25ce0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 objects..**.**
25cf0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 These routines w
25d00 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 ork only with [p
25d10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
25d20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
25d30 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 .** Any attempt
25d40 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 to use these rou
25d50 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 tines on an [unp
25d60 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
25d70 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 _value].** objec
25d80 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 t results in und
25d90 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e efined behavior.
25da0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
25db0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 tines work just
25dc0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 like the corresp
25dd0 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 onding [column a
25de0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d ccess functions]
25df0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
25e00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
25e10 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 take a single [p
25e20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
25e30 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a _value] object.*
25e40 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 * pointer instea
25e50 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f d of a [sqlite3_
25e60 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 stmt*] pointer a
25e70 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f nd an integer co
25e80 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a lumn number..**.
25e90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ** The sqlite3_v
25ea0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e alue_text16() in
25eb0 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 terface extracts
25ec0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 a UTF-16 string
25ed0 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 .** in the nativ
25ee0 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 e byte-order of
25ef0 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 the host machine
25f00 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 . The.** sqlite
25f10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
25f20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 () and sqlite3_v
25f30 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 alue_text16le()
25f40 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 interfaces.** ex
25f50 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 tract UTF-16 str
25f60 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 ings as big-endi
25f70 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e an and little-en
25f80 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c dian respectivel
25f90 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c y..**.** The sql
25fa0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 ite3_value_numer
25fb0 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 ic_type() interf
25fc0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
25fd0 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 apply.** numeric
25fe0 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 affinity to the
25ff0 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 value. This me
26000 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 ans that an atte
26010 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 mpt is.** made t
26020 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 o convert the va
26030 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 lue to an intege
26040 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f r or floating po
26050 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 int. If.** such
26060 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 a conversion is
26070 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 possible withou
26080 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d t loss of inform
26090 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a ation (in other.
260a0 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 ** words, if the
260b0 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 value is a stri
260c0 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 ng that looks li
260d0 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 ke a number).**
260e0 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 then the convers
260f0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 ion is performed
26100 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 . Otherwise no
26110 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
26120 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 s..** The [SQLIT
26130 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 E_INTEGER | data
26140 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 type] after conv
26150 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e ersion is return
26160 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 ed..**.** Please
26170 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 pay particular
26180 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 attention to the
26190 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 fact that the p
261a0 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a ointer returned.
261b0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
261c0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 _value_blob()],
261d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
261e0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 ext()], or.** [s
261f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
26200 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e t16()] can be in
26210 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 validated by a s
26220 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 ubsequent call t
26230 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 o.** [sqlite3_va
26240 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 lue_bytes()], [s
26250 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
26260 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 es16()], [sqlite
26270 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
26280 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
26290 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e value_text16()].
262a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
262b0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 tines must be ca
262c0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 lled from the sa
262d0 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 me thread as.**
262e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
262f0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 that supplied t
26300 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
26310 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a e*] parameters..
26320 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
26330 74 73 3a 0a 2a 2a 20 5b 48 31 35 31 30 33 5d 20 ts:.** [H15103]
26340 5b 48 31 35 31 30 36 5d 20 5b 48 31 35 31 30 39 [H15106] [H15109
26350 5d 20 5b 48 31 35 31 31 32 5d 20 5b 48 31 35 31 ] [H15112] [H151
26360 31 35 5d 20 5b 48 31 35 31 31 38 5d 20 5b 48 31 15] [H15118] [H1
26370 35 31 32 31 5d 20 5b 48 31 35 31 32 34 5d 0a 2a 5121] [H15124].*
26380 2a 20 5b 48 31 35 31 32 37 5d 20 5b 48 31 35 31 * [H15127] [H151
26390 33 30 5d 20 5b 48 31 35 31 33 33 5d 20 5b 48 31 30] [H15133] [H1
263a0 35 31 33 36 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 5136].*/.SQLITE_
263b0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
263c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
263d0 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ob(sqlite3_value
263e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
263f0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
26400 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 _bytes(sqlite3_v
26410 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
26420 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 PI int sqlite3_v
26430 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c alue_bytes16(sql
26440 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
26450 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 LITE_API double
26460 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f sqlite3_value_do
26470 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c uble(sqlite3_val
26480 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
26490 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c int sqlite3_val
264a0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 ue_int(sqlite3_v
264b0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
264c0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 PI sqlite3_int64
264d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 sqlite3_value_i
264e0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c nt64(sqlite3_val
264f0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
26500 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 const unsigned
26510 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 char *sqlite3_va
26520 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 lue_text(sqlite3
26530 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
26540 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
26550 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
26560 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 ext16(sqlite3_va
26570 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
26580 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
26590 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
265a0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 16le(sqlite3_val
265b0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
265c0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
265d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
265e0 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 6be(sqlite3_valu
265f0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
26600 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
26610 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 e_type(sqlite3_v
26620 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
26630 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 PI int sqlite3_v
26640 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
26650 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
26660 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
26670 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 EF: Obtain Aggre
26680 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f gate Function Co
26690 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c ntext {H16210} <
266a0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20200>.**.** Th
266b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
266c0 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 of aggregate SQ
266d0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 L functions use
266e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 this routine to
266f0 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 allocate.** a st
26700 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 ructure for stor
26710 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e ing their state.
26720 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
26730 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 time the sqlite
26740 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
26750 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ext() routine is
26760 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a called for a.**
26770 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 particular aggr
26780 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c egate, SQLite al
26790 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f locates nBytes o
267a0 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 f memory, zeroes
267b0 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d out that.** mem
267c0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 ory, and returns
267d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 a pointer to it
267e0 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 . On second and
267f0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
26800 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 to.** sqlite3_a
26810 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
26820 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 () for the same
26830 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
26840 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 on index,.** the
26850 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 same buffer is
26860 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d returned. The im
26870 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
26880 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 the aggregate ca
26890 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 n use.** the ret
268a0 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 urned buffer to
268b0 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e accumulate data.
268c0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 .**.** SQLite au
268d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 tomatically free
268e0 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 s the allocated
268f0 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 buffer when the
26900 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 aggregate.** que
26910 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a ry concludes..**
26920 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
26930 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 rameter should b
26940 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a e a copy of the.
26950 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
26960 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 ext | SQL functi
26970 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 on context] that
26980 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 is the first pa
26990 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
269a0 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 e callback routi
269b0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ne that implemen
269c0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 ts the aggregate
269d0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
269e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 This routine mu
269f0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
26a00 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
26a10 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 d in which.** th
26a20 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 e aggregate SQL
26a30 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
26a40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ing..**.** Requi
26a50 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 rements:.** [H16
26a60 32 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 5b 48 211] [H16213] [H
26a70 31 36 32 31 35 5d 20 5b 48 31 36 32 31 37 5d 0a 16215] [H16217].
26a80 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
26a90 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 id *sqlite3_aggr
26aa0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 egate_context(sq
26ab0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
26ac0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a int nBytes);../*
26ad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 .** CAPI3REF: Us
26ae0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 er Data For Func
26af0 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c tions {H16240} <
26b00 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20200>.**.** Th
26b10 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 e sqlite3_user_d
26b20 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
26b30 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
26b40 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 f.** the pointer
26b50 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 that was the pU
26b60 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 serData paramete
26b70 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d r (the 5th param
26b80 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
26b90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
26ba0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
26bb0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
26bc0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
26bd0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
26be0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
26bf0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
26c00 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
26c10 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a function. {END}.
26c20 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
26c30 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ne must be calle
26c40 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
26c50 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
26c60 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
26c70 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
26c80 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
26c90 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
26ca0 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 34 33 5d 0a ts:.** [H16243].
26cb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
26cc0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 id *sqlite3_user
26cd0 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f _data(sqlite3_co
26ce0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
26cf0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 CAPI3REF: Databa
26d00 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f se Connection Fo
26d10 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 r Functions {H16
26d20 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 250} <S60600><S2
26d30 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0200>.**.** The
26d40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f sqlite3_context_
26d50 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 db_handle() inte
26d60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
26d70 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 copy of.** the p
26d80 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 ointer to the [d
26d90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
26da0 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 on] (the 1st par
26db0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 ameter).** of th
26dc0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 e [sqlite3_creat
26dd0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a e_function()].**
26de0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
26df0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
26e00 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 )] routines that
26e10 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 originally.** r
26e20 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 egistered the ap
26e30 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 plication define
26e40 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a d function..**.*
26e50 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
26e60 2a 2a 20 5b 48 31 36 32 35 33 5d 0a 2a 2f 0a 53 ** [H16253].*/.S
26e70 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
26e80 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 3 *sqlite3_conte
26e90 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c xt_db_handle(sql
26ea0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
26eb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
26ec0 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 Function Auxili
26ed0 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 ary Data {H16270
26ee0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
26ef0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 The following t
26f00 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 wo functions may
26f10 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c be used by scal
26f20 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ar SQL functions
26f30 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 to.** associate
26f40 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 metadata with a
26f50 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 rgument values.
26f60 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 If the same valu
26f70 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a e is passed to.*
26f80 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 * multiple invoc
26f90 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
26fa0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 me SQL function
26fb0 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 during query exe
26fc0 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a cution, under.**
26fd0 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e some circumstan
26fe0 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 ces the associat
26ff0 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 ed metadata may
27000 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 be preserved. Th
27010 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 is may.** be use
27020 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 d, for example,
27030 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 to add a regular
27040 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 -expression matc
27050 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 hing scalar.** f
27060 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d unction. The com
27070 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 piled version of
27080 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 the regular exp
27090 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 ression is store
270a0 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 d as.** metadata
270b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
270c0 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 the SQL value p
270d0 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 assed as the reg
270e0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a ular expression.
270f0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 ** pattern. The
27100 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 compiled regula
27110 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e r expression can
27120 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 be reused on mu
27130 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 ltiple.** invoca
27140 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
27150 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 e function so th
27160 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 at the original
27170 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a pattern string.*
27180 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 * does not need
27190 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 to be recompiled
271a0 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 on each invocat
271b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
271c0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
271d0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ta() interface r
271e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
271f0 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 to the metadata
27200 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 .** associated b
27210 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 y the sqlite3_se
27220 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 t_auxdata() func
27230 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 tion with the Nt
27240 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 h argument.** va
27250 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 lue to the appli
27260 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
27270 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d unction. If no m
27280 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e etadata has been
27290 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 ever.** been se
272a0 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 t for the Nth ar
272b0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 gument of the fu
272c0 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 nction, or if th
272d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a e corresponding.
272e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 ** function para
272f0 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 meter has change
27300 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 d since the meta
27310 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a -data was set,.*
27320 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 * then sqlite3_g
27330 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 et_auxdata() ret
27340 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
27350 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ter..**.** The s
27360 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
27370 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ta() interface s
27380 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 aves the metadat
27390 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 a.** pointed to
273a0 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d by its 3rd param
273b0 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 eter as the meta
273c0 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 data for the N-t
273d0 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 h.** argument of
273e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
273f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
27400 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a n. Subsequent.*
27410 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 * calls to sqlit
27420 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
27430 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 might return th
27440 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 is data, if it h
27450 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 as.** not been d
27460 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 estroyed..** If
27470 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 it is not NULL,
27480 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f SQLite will invo
27490 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f ke the destructo
274a0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 r.** function gi
274b0 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 ven by the 4th p
274c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
274d0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
274e0 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 ) on.** the meta
274f0 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f data when the co
27500 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 rresponding func
27510 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 tion parameter c
27520 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 hanges.** or whe
27530 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d n the SQL statem
27540 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 ent completes, w
27550 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 hichever comes f
27560 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 irst..**.** SQLi
27570 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 te is free to ca
27580 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f ll the destructo
27590 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 r and drop metad
275a0 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 ata on any.** pa
275b0 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 rameter of any f
275c0 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 unction at any t
275d0 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 ime. The only g
275e0 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 uarantee is that
275f0 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 .** the destruct
27600 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 or will be calle
27610 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 d before the met
27620 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 adata is dropped
27630 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 ..**.** In pract
27640 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 ice, metadata is
27650 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 preserved betwe
27660 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c en function call
27670 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 s for.** express
27680 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f ions that are co
27690 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c nstant at compil
276a0 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 e time. This inc
276b0 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a ludes literal.**
276c0 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 values and SQL
276d0 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a variables..**.**
276e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
276f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
27700 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
27710 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
27720 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
27730 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a is running..**.
27740 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
27750 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 31 .** [H16272] [H1
27760 36 32 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 5b 6274] [H16276] [
27770 48 31 36 32 37 37 5d 20 5b 48 31 36 32 37 38 5d H16277] [H16278]
27780 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 53 51 4c [H16279].*/.SQL
27790 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 ITE_API void *sq
277a0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
277b0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
277c0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 t*, int N);.SQLI
277d0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
277e0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
277f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
27800 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 , int N, void*,
27810 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 void (*)(void*))
27820 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
27830 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 EF: Constants De
27840 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 fining Special D
27850 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 estructor Behavi
27860 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 or {H10280} <S30
27870 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 100>.**.** These
27880 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c are special val
27890 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 ues for the dest
278a0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 ructor that is p
278b0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a assed in as the.
278c0 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e ** final argumen
278d0 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 t to routines li
278e0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ke [sqlite3_resu
278f0 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 lt_blob()]. If
27900 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a the destructor.*
27910 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 * argument is SQ
27920 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 LITE_STATIC, it
27930 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 means that the c
27940 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 ontent pointer i
27950 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e s constant.** an
27960 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 d will never cha
27970 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f nge. It does no
27980 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 t need to be des
27990 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 troyed. The.**
279a0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
279b0 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 value means tha
279c0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 t the content wi
279d0 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 ll likely change
279e0 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 in.** the near
279f0 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 future and that
27a00 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 SQLite should ma
27a10 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 ke its own priva
27a20 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 te copy of.** th
27a30 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 e content before
27a40 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a returning..**.*
27a50 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 * The typedef is
27a60 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f necessary to wo
27a70 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 rk around proble
27a80 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a ms in certain.**
27a90 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 C++ compilers.
27aa0 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 See ticket #219
27ab0 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 1..*/.typedef vo
27ac0 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 id (*sqlite3_des
27ad0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f tructor_type)(vo
27ae0 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 id*);.#define SQ
27af0 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 LITE_STATIC
27b00 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 ((sqlite3_destr
27b10 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 uctor_type)0).#d
27b20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
27b30 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 NSIENT ((sqlit
27b40 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 e3_destructor_ty
27b50 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 pe)-1)../*.** CA
27b60 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 PI3REF: Setting
27b70 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e The Result Of An
27b80 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 SQL Function {H
27b90 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 16400} <S20200>.
27ba0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
27bb0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 ines are used by
27bc0 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 the xFunc or xF
27bd0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 inal callbacks t
27be0 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 hat.** implement
27bf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
27c00 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 nd aggregates.
27c10 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f See.** [sqlite3_
27c20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
27c30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
27c40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
27c50 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 6()].** for addi
27c60 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
27c70 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 on..**.** These
27c80 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 functions work v
27c90 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 ery much like th
27ca0 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e e [parameter bin
27cb0 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a ding] family of.
27cc0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 ** functions use
27cd0 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 d to bind values
27ce0 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 to host paramet
27cf0 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 ers in prepared
27d00 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 statements..** R
27d10 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c efer to the [SQL
27d20 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 parameter] docu
27d30 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
27d40 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
27d50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
27d60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
27d70 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 lob() interface
27d80 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 sets the result
27d90 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 from.** an appli
27da0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
27db0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
27dc0 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e e BLOB whose con
27dd0 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a tent is pointed.
27de0 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 ** to by the sec
27df0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e ond parameter an
27e00 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 d which is N byt
27e10 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 es long where N
27e20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 is the.** third
27e30 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
27e40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
27e50 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 ult_zeroblob() i
27e60 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 nterfaces set th
27e70 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 e result of.** t
27e80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
27e90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
27ea0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e to be a BLOB con
27eb0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f taining all zero
27ec0 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 .** bytes and N
27ed0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 bytes in size, w
27ee0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 here N is the va
27ef0 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 lue of the 2nd p
27f00 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
27f10 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
27f20 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 lt_double() inte
27f30 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
27f40 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e esult from.** an
27f50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
27f60 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
27f70 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 be a floating p
27f80 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 oint value speci
27f90 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 fied.** by its 2
27fa0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
27fb0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
27fc0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e esult_error() an
27fd0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
27fe0 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 _error16() funct
27ff0 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 ions.** cause th
28000 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 e implemented SQ
28010 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 L function to th
28020 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e row an exception
28030 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 ..** SQLite uses
28040 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e the string poin
28050 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a ted to by the.**
28060 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
28070 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 f sqlite3_result
28080 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 _error() or sqli
28090 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
280a0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 16().** as the t
280b0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 ext of an error
280c0 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 message. SQLite
280d0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 interprets the
280e0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
280f0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
28100 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
28110 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51 r() as UTF-8. SQ
28120 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 Lite.** interpre
28130 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 ts the string fr
28140 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c om sqlite3_resul
28150 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 t_error16() as U
28160 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a TF-16 in native.
28170 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 ** byte order.
28180 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
28190 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
281a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
281b0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
281c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
281d0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e is negative then
281e0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 SQLite takes as
281f0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 the error.** me
28200 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 ssage all text u
28210 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 p through the fi
28220 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 rst zero charact
28230 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 er..** If the th
28240 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
28250 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28260 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 error() or.** sq
28270 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
28280 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 or16() is non-ne
28290 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
282a0 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 te takes that ma
282b0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 ny.** bytes (not
282c0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f characters) fro
282d0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 m the 2nd parame
282e0 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 ter as the error
282f0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 message..** The
28300 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28310 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 error() and sqli
28320 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
28330 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 16().** routines
28340 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 make a private
28350 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f copy of the erro
28360 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 r message text b
28370 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 efore.** they re
28380 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 turn. Hence, th
28390 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 e calling functi
283a0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 on can deallocat
283b0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 e or.** modify t
283c0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 he text after th
283d0 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 ey return withou
283e0 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 t harm..** The s
283f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
28400 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 ror_code() funct
28410 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 ion changes the
28420 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 error code.** re
28430 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 turned by SQLite
28440 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 as a result of
28450 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 an error in a fu
28460 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 nction. By defa
28470 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f ult,.** the erro
28480 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 r code is SQLITE
28490 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 _ERROR. A subse
284a0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 quent call to sq
284b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
284c0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 or().** or sqlit
284d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
284e0 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 6() resets the e
284f0 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c rror code to SQL
28500 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a ITE_ERROR..**.**
28510 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
28520 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 ult_toobig() int
28530 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 erface causes SQ
28540 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e Lite to throw an
28550 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 error.** indica
28560 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 ting that a stri
28570 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f ng or BLOB is to
28580 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 long to represe
28590 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 nt..**.** The sq
285a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d lite3_result_nom
285b0 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 em() interface c
285c0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 auses SQLite to
285d0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a throw an error.*
285e0 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 * indicating tha
285f0 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 t a memory alloc
28600 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a ation failed..**
28610 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
28620 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 result_int() int
28630 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
28640 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
28650 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
28660 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
28670 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 ion to be the 32
28680 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
28690 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 ger.** value giv
286a0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 en in the 2nd ar
286b0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 gument..** The s
286c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
286d0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 t64() interface
286e0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 sets the return
286f0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 value.** of the
28700 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
28710 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
28720 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 be the 64-bit si
28730 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 gned integer.**
28740 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 value given in t
28750 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e he 2nd argument.
28760 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
28770 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 e3_result_null()
28780 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
28790 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
287a0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
287b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
287c0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 unction to be NU
287d0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 LL..**.** The sq
287e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
287f0 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 t(), sqlite3_res
28800 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a ult_text16(),.**
28810 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28820 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 text16le(), and
28830 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
28840 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 ext16be() interf
28850 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 aces.** set the
28860 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
28870 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
28880 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
28890 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 to be.** a text
288a0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
288b0 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 represented as
288c0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 UTF-8, UTF-16 na
288d0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c tive byte order,
288e0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c .** UTF-16 littl
288f0 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 e endian, or UTF
28900 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 -16 big endian,
28910 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
28920 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 SQLite takes th
28930 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 e text result fr
28940 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 om the applicati
28950 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 on from.** the 2
28960 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 nd parameter of
28970 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
28980 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
28990 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 ces..** If the 3
289a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
289b0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
289c0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
289d0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 ces.** is negati
289e0 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 ve, then SQLite
289f0 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 takes result tex
28a00 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 t from the 2nd p
28a10 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f arameter.** thro
28a20 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 ugh the first ze
28a30 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a ro character..**
28a40 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
28a50 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
28a60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
28a70 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
28a80 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
28a90 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 then as many by
28aa0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 tes (not charact
28ab0 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 ers) of the text
28ac0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 .** pointed to b
28ad0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 y the 2nd parame
28ae0 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 ter are taken as
28af0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
28b00 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 -defined.** func
28b10 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 tion result..**
28b20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d If the 4th param
28b30 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
28b40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
28b50 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f interfaces.** o
28b60 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
28b70 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e _blob is a non-N
28b80 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
28b90 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 n SQLite calls t
28ba0 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 hat.** function
28bb0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f as the destructo
28bc0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 r on the text or
28bd0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 BLOB result whe
28be0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 n it has.** fini
28bf0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 shed using that
28c00 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 result..** If th
28c10 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
28c20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
28c30 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
28c40 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 rfaces or to.**
28c50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
28c60 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 lob is the speci
28c70 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 al constant SQLI
28c80 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 TE_STATIC, then
28c90 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 SQLite.** assume
28ca0 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 s that the text
28cb0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 or BLOB result i
28cc0 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 s in constant sp
28cd0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ace and does not
28ce0 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e .** copy the con
28cf0 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 tent of the para
28d00 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 meter nor call a
28d10 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 destructor on t
28d20 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 he content.** wh
28d30 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 en it has finish
28d40 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 ed using that re
28d50 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 sult..** If the
28d60 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
28d70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
28d80 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
28d90 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 aces.** or sqlit
28da0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 e3_result_blob i
28db0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f s the special co
28dc0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 nstant SQLITE_TR
28dd0 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 ANSIENT.** then
28de0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
28df0 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c opy of the resul
28e00 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 t into space obt
28e10 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 ained from.** fr
28e20 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
28e30 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 oc()] before it
28e40 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 returns..**.** T
28e50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
28e60 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 t_value() interf
28e70 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
28e80 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
28e90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
28ea0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
28eb0 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b a copy the.** [
28ec0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
28ed0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
28ee0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 t specified by t
28ef0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
28f00 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 . The.** sqlite
28f10 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
28f20 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 interface makes
28f30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b a copy of the [
28f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a sqlite3_value].*
28f50 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 * so that the [s
28f60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 qlite3_value] sp
28f70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 ecified in the p
28f80 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 arameter may cha
28f90 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 nge or.** be dea
28fa0 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 llocated after s
28fb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
28fc0 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 lue() returns wi
28fd0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 thout harm..** A
28fe0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
28ff0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
29000 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 t may always be
29010 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a used where an.**
29020 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
29030 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
29040 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c ect is required,
29050 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 so either.** ki
29060 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 nd of [sqlite3_v
29070 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e alue] object can
29080 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 be used with th
29090 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
290a0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 .** If these rou
290b0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
290c0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
290d0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
290e0 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e d.** than the on
290f0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
29100 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
29110 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 ined function th
29120 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 at received.** t
29130 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
29140 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 ext] pointer, th
29150 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
29160 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 defined..**.** R
29170 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
29180 5b 48 31 36 34 30 33 5d 20 5b 48 31 36 34 30 36 [H16403] [H16406
29190 5d 20 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 34 ] [H16409] [H164
291a0 31 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 31 12] [H16415] [H1
291b0 36 34 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 5b 6418] [H16421] [
291c0 48 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 H16424].** [H164
291d0 32 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 31 27] [H16430] [H1
291e0 36 34 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 5b 6433] [H16436] [
291f0 48 31 36 34 33 39 5d 20 5b 48 31 36 34 34 32 5d H16439] [H16442]
29200 20 5b 48 31 36 34 34 35 5d 20 5b 48 31 36 34 34 [H16445] [H1644
29210 38 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 5b 8].** [H16451] [
29220 48 31 36 34 35 34 5d 20 5b 48 31 36 34 35 37 5d H16454] [H16457]
29230 20 5b 48 31 36 34 36 30 5d 20 5b 48 31 36 34 36 [H16460] [H1646
29240 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 3].*/.SQLITE_API
29250 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
29260 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 sult_blob(sqlite
29270 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
29280 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
29290 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 id(*)(void*));.S
292a0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
292b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
292c0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e uble(sqlite3_con
292d0 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a text*, double);.
292e0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
292f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
29300 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e rror(sqlite3_con
29310 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
29320 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 r*, int);.SQLITE
29330 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
29340 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
29350 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29360 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
29370 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
29380 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
29390 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 sult_error_toobi
293a0 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 g(sqlite3_contex
293b0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
293c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
293d0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 ult_error_nomem(
293e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
293f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
29400 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
29410 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c t_error_code(sql
29420 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
29430 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
29440 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
29450 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f ult_int(sqlite3_
29460 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a context*, int);.
29470 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
29480 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
29490 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e nt64(sqlite3_con
294a0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 text*, sqlite3_i
294b0 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 nt64);.SQLITE_AP
294c0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
294d0 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 esult_null(sqlit
294e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
294f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
29500 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
29510 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
29520 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
29530 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
29540 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
29550 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
29560 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c esult_text16(sql
29570 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
29580 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
29590 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
295a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
295b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
295c0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
295d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
295e0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 t void*, int,voi
295f0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
29600 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
29610 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
29620 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f t16be(sqlite3_co
29630 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
29640 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 id*, int,void(*)
29650 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 (void*));.SQLITE
29660 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
29670 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 3_result_value(s
29680 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
29690 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 sqlite3_value*)
296a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
296b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
296c0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 _zeroblob(sqlite
296d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
296e0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 n);../*.** CAPI3
296f0 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 REF: Define New
29700 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e Collating Sequen
29710 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 ces {H16600} <S2
29720 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0300>.**.** Thes
29730 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 e functions are
29740 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 used to add new
29750 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
29760 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 ces to the.** [d
29770 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
29780 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 on] specified as
29790 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
297a0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e ent..**.** The n
297b0 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 ame of the new c
297c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
297d0 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 e is specified a
297e0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 s a UTF-8 string
297f0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f .** for sqlite3_
29800 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
29810 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
29820 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
29830 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 v2().** and a UT
29840 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 F-16 string for
29850 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
29860 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e ollation16(). In
29870 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 all cases.** th
29880 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 e name is passed
29890 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 as the second f
298a0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
298b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 ..**.** The thir
298c0 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 d argument may b
298d0 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e e one of the con
298e0 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 stants [SQLITE_U
298f0 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 TF8],.** [SQLITE
29900 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 _UTF16LE], or [S
29910 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 QLITE_UTF16BE],
29920 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 indicating that
29930 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 the user-supplie
29940 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 d.** routine exp
29950 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 ects to be passe
29960 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 d pointers to st
29970 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 rings encoded us
29980 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 ing UTF-8,.** UT
29990 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 F-16 little-endi
299a0 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 an, or UTF-16 bi
299b0 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 g-endian, respec
299c0 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 tively. The.** t
299d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 hird argument mi
299e0 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c ght also be [SQL
299f0 49 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e ITE_UTF16] to in
29a00 64 69 63 61 74 65 20 74 68 61 74 20 74 68 65 20 dicate that the
29a10 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 routine.** expec
29a20 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 ts pointers to b
29a30 65 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 e UTF-16 strings
29a40 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
29a50 79 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 yte order, or th
29a60 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 e.** argument ca
29a70 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 n be [SQLITE_UTF
29a80 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 16_ALIGNED] if t
29a90 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e he.** the routin
29aa0 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 e expects pointe
29ab0 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 rs to 16-bit wor
29ac0 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 d aligned string
29ad0 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 s.** of UTF-16 i
29ae0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
29af0 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 e order..**.** A
29b00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
29b10 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f user supplied ro
29b20 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 utine must be pa
29b30 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 ssed as the fift
29b40 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 h.** argument.
29b50 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 If it is NULL, t
29b60 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 his is the same
29b70 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 as deleting the
29b80 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 collation.** seq
29b90 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 uence (so that S
29ba0 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c QLite cannot cal
29bb0 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a l it anymore)..*
29bc0 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 * Each time the
29bd0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 application supp
29be0 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 lied function is
29bf0 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 invoked, it is
29c00 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 passed.** as its
29c10 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
29c20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 a copy of the v
29c30 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 oid* passed as t
29c40 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
29c50 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 nt.** to sqlite3
29c60 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
29c70 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 n() or sqlite3_c
29c80 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
29c90 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 6()..**.** The r
29ca0 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e emaining argumen
29cb0 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 ts to the applic
29cc0 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 ation-supplied r
29cd0 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 outine are two s
29ce0 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 trings,.** each
29cf0 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 represented by a
29d00 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 (length, data)
29d10 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 pair and encoded
29d20 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 in the encoding
29d30 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 .** that was pas
29d40 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
29d50 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 argument when t
29d60 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 he collation seq
29d70 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 uence was.** reg
29d80 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 istered. {END}
29d90 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
29da0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f defined collatio
29db0 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 n routine should
29dc0 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 .** return negat
29dd0 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 ive, zero or pos
29de0 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 itive if the fir
29df0 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 st string is les
29e00 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c s than,.** equal
29e10 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 to, or greater
29e20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 than the second
29e30 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 string. i.e. (ST
29e40 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 RING1 - STRING2)
29e50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
29e60 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
29e70 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 tion_v2() works
29e80 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 like sqlite3_cre
29e90 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a ate_collation().
29ea0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 ** except that i
29eb0 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 t takes an extra
29ec0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
29ed0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 is a destructor
29ee0 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 for.** the colla
29ef0 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 tion. The destr
29f00 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 uctor is called
29f10 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 when the collati
29f20 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 on is.** destroy
29f30 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 ed and is passed
29f40 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 a copy of the f
29f50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
29f60 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a void* pointer.**
29f70 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
29f80 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
29f90 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 _v2()..** Collat
29fa0 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 ions are destroy
29fb0 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 ed when they are
29fc0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c overridden by l
29fd0 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 ater calls to th
29fe0 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 e.** collation c
29ff0 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e reation function
2a000 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 s or when the [d
2a010 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2a020 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a on] is closed.**
2a030 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2a040 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 close()]..**.**
2a050 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 See also: [sqli
2a060 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
2a070 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c eded()] and [sql
2a080 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
2a090 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a eeded16()]..**.*
2a0a0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
2a0b0 2a 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 36 ** [H16603] [H16
2a0c0 36 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48 604] [H16606] [H
2a0d0 31 36 36 30 39 5d 20 5b 48 31 36 36 31 32 5d 20 16609] [H16612]
2a0e0 5b 48 31 36 36 31 35 5d 20 5b 48 31 36 36 31 38 [H16615] [H16618
2a0f0 5d 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 ] [H16621].** [H
2a100 31 36 36 32 34 5d 20 5b 48 31 36 36 32 37 5d 20 16624] [H16627]
2a110 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a 53 51 4c 49 [H16630].*/.SQLI
2a120 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2a130 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
2a140 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c ion(. sqlite3*,
2a150 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a . const char *
2a160 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 zName, . int eT
2a170 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a extRep, . void*
2a180 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
2a190 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
2a1a0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
2a1b0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c st void*).);.SQL
2a1c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2a1d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
2a1e0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 tion_v2(. sqlit
2a1f0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 e3*, . const ch
2a200 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e ar *zName, . in
2a210 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 t eTextRep, . v
2a220 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f oid*,. int(*xCo
2a230 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
2a240 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
2a250 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 ,const void*),.
2a260 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 void(*xDestroy)
2a270 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 (void*).);.SQLIT
2a280 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2a290 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2a2a0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a on16(. sqlite3*
2a2b0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 , . const void
2a2c0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 *zName,. int eT
2a2d0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a extRep, . void*
2a2e0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
2a2f0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
2a300 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
2a310 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
2a320 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
2a330 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 llation Needed C
2a340 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 allbacks {H16700
2a350 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S20300>.**.**
2a360 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 To avoid having
2a370 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c to register all
2a380 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
2a390 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 nces before a da
2a3a0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 tabase.** can be
2a3b0 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 used, a single
2a3c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
2a3d0 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 n may be registe
2a3e0 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 red with the.**
2a3f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2a400 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c tion] to be call
2a410 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 ed whenever an u
2a420 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 ndefined collati
2a430 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 on.** sequence i
2a440 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a s required..**.*
2a450 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f * If the functio
2a460 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 n is registered
2a470 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
2a480 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
2a490 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 ed() API,.** the
2a4a0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 n it is passed t
2a4b0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 he names of unde
2a4c0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 fined collation
2a4d0 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 sequences as str
2a4e0 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 ings.** encoded
2a4f0 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 in UTF-8. {H1670
2a500 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 3} If sqlite3_co
2a510 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
2a520 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 () is used,.** t
2a530 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 he names are pas
2a540 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e sed as UTF-16 in
2a550 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 machine native
2a560 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 byte order..** A
2a570 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 call to either
2a580 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 function replace
2a590 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 s any existing c
2a5a0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 allback..**.** W
2a5b0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
2a5c0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 is invoked, the
2a5d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
2a5e0 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 passed is a copy
2a5f0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e .** of the secon
2a600 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
2a610 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
2a620 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 needed() or.** s
2a630 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
2a640 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 _needed16(). Th
2a650 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
2a660 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 t is the databas
2a670 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
2a680 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 The third argu
2a690 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
2a6a0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 SQLITE_UTF8], [S
2a6b0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a QLITE_UTF16BE],.
2a6c0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 ** or [SQLITE_UT
2a6d0 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 F16LE], indicati
2a6e0 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 ng the most desi
2a6f0 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 rable form of th
2a700 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 e collation.** s
2a710 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e equence function
2a720 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 required. The
2a730 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2a740 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
2a750 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 the.** required
2a760 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
2a770 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 ce..**.** The ca
2a780 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
2a790 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 should register
2a7a0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c the desired coll
2a7b0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b ation using.** [
2a7c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
2a7d0 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 ollation()], [sq
2a7e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
2a7f0 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a lation16()], or.
2a800 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
2a810 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
2a820 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
2a830 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 ements:.** [H167
2a840 30 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 02] [H16704] [H1
2a850 36 37 30 36 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 6706].*/.SQLITE_
2a860 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2a870 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
2a880 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
2a890 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 void*, . void(
2a8a0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
2a8b0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 *,int eTextRep,c
2a8c0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53 onst char*).);.S
2a8d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2a8e0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
2a8f0 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 needed16(. sqli
2a900 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a te3*, . void*,.
2a910 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c void(*)(void*,
2a920 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 sqlite3*,int eTe
2a930 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 xtRep,const void
2a940 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 *).);../*.** Spe
2a950 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 cify the key for
2a960 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 an encrypted da
2a970 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f tabase. This ro
2a980 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a utine should be.
2a990 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 ** called right
2a9a0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 after sqlite3_op
2a9b0 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 en()..**.** The
2a9c0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e code to implemen
2a9d0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f t this API is no
2a9e0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 t available in t
2a9f0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 he public releas
2aa00 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a e.** of SQLite..
2aa10 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2aa20 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 t sqlite3_key(.
2aa30 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
2aa40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2aa50 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 /* Database to b
2aa60 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 e rekeyed */. c
2aa70 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c onst void *pKey,
2aa80 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a int nKey /*
2aa90 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a The key */.);..
2aaa0 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 /*.** Change the
2aab0 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 key on an open
2aac0 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 database. If th
2aad0 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 e current databa
2aae0 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 se is not.** enc
2aaf0 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 rypted, this rou
2ab00 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 tine will encryp
2ab10 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d t it. If pNew==
2ab20 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 0 or nNew==0, th
2ab30 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 e.** database is
2ab40 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a decrypted..**.*
2ab50 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d * The code to im
2ab60 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 plement this API
2ab70 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c is not availabl
2ab80 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 e in the public
2ab90 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 release.** of SQ
2aba0 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f Lite..*/.SQLITE_
2abb0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2abc0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 rekey(. sqlite3
2abd0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2abe0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
2abf0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 ase to be rekeye
2ac00 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 d */. const voi
2ac10 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 d *pKey, int nKe
2ac20 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 y /* The new
2ac30 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a key */.);../*.*
2ac40 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 * CAPI3REF: Susp
2ac50 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f end Execution Fo
2ac60 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b r A Short Time {
2ac70 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30 3e H10530} <S40410>
2ac80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2ac90 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 e3_sleep() funct
2aca0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 ion causes the c
2acb0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f urrent thread to
2acc0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 suspend executi
2acd0 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 on.** for at lea
2ace0 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d st a number of m
2acf0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 illiseconds spec
2ad00 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 ified in its par
2ad10 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 ameter..**.** If
2ad20 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
2ad30 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 ystem does not s
2ad40 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 upport sleep req
2ad50 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 uests with.** mi
2ad60 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 llisecond time r
2ad70 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 esolution, then
2ad80 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 the time will be
2ad90 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a rounded up to.*
2ada0 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 * the nearest se
2adb0 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 cond. The number
2adc0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 of milliseconds
2add0 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c of sleep actual
2ade0 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 ly.** requested
2adf0 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 from the operati
2ae00 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 ng system is ret
2ae10 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c urned..**.** SQL
2ae20 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 ite implements t
2ae30 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 his interface by
2ae40 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c calling the xSl
2ae50 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 eep().** method
2ae60 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b of the default [
2ae70 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
2ae80 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ect..**.** Requi
2ae90 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 33 33 rements: [H10533
2aea0 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a 53 51 ] [H10536].*/.SQ
2aeb0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2aec0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b ite3_sleep(int);
2aed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2aee0 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f : Name Of The Fo
2aef0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d lder Holding Tem
2af00 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31 porary Files {H1
2af10 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 0310} <S20000>.*
2af20 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f *.** If this glo
2af30 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 bal variable is
2af40 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
2af50 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 a string which
2af60 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f is.** the name o
2af70 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e f a folder (a.k.
2af80 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 a. directory), t
2af90 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 hen all temporar
2afa0 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 y files.** creat
2afb0 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c ed by SQLite wil
2afc0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 l be placed in t
2afd0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 hat directory.
2afe0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 If this variable
2aff0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f .** is a NULL po
2b000 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 inter, then SQLi
2b010 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 te performs a se
2b020 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 arch for an appr
2b030 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f opriate.** tempo
2b040 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 rary file direct
2b050 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 ory..**.** It is
2b060 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 not safe to rea
2b070 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 d or modify this
2b080 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 variable in mor
2b090 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 e than one.** th
2b0a0 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 read at a time.
2b0b0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
2b0c0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 to read or modif
2b0d0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a y this variable.
2b0e0 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 ** if a [databas
2b0f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 e connection] is
2b100 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 being used at t
2b110 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 he same time in
2b120 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 a separate.** th
2b130 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 read..** It is i
2b140 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 ntended that thi
2b150 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 s variable be se
2b160 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 t once.** as par
2b170 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 t of process ini
2b180 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 tialization and
2b190 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 before any SQLit
2b1a0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 e interface.** r
2b1b0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 outines have bee
2b1c0 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 n called and tha
2b1d0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 t this variable
2b1e0 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 remain unchanged
2b1f0 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a .** thereafter..
2b200 2a 2a 0a 2a 2a 20 54 68 65 20 5b 74 65 6d 70 5f **.** The [temp_
2b210 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
2b220 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 pragma] may modi
2b230 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 fy this variable
2b240 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 and cause.** it
2b250 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d to point to mem
2b260 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
2b270 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
2b280 63 5d 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 c]. Furthermore
2b290 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 ,.** the [temp_s
2b2a0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
2b2b0 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 ragma] always as
2b2c0 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 sumes that any s
2b2d0 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 tring.** that th
2b2e0 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e is variable poin
2b2f0 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e ts to is held in
2b300 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
2b310 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 from .** [sqlit
2b320 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 e3_malloc] and t
2b330 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 he pragma may at
2b340 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 tempt to free th
2b350 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 at memory.** usi
2b360 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ng [sqlite3_free
2b370 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 ]..** Hence, if
2b380 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 this variable is
2b390 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 modified direct
2b3a0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 ly, either it sh
2b3b0 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 ould be.** made
2b3c0 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 NULL or made to
2b3d0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 point to memory
2b3e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
2b3f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a qlite3_malloc].*
2b400 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 * or else the us
2b410 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 e of the [temp_s
2b420 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
2b430 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 ragma] should be
2b440 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c avoided..*/.SQL
2b450 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 ITE_API SQLITE_E
2b460 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 XTERN char *sqli
2b470 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f te3_temp_directo
2b480 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ry;../*.** CAPI3
2b490 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 REF: Test For Au
2b4a0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b to-Commit Mode {
2b4b0 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e H12930} <S60200>
2b4c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 .** KEYWORDS: {a
2b4d0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a utocommit mode}.
2b4e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
2b4f0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 3_get_autocommit
2b500 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
2b510 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 urns non-zero or
2b520 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 .** zero if the
2b530 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 given database c
2b540 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 onnection is or
2b550 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f is not in autoco
2b560 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 mmit mode,.** re
2b570 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74 spectively. Aut
2b580 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 ocommit mode is
2b590 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a on by default..*
2b5a0 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 * Autocommit mod
2b5b0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 e is disabled by
2b5c0 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 a [BEGIN] state
2b5d0 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d ment..** Autocom
2b5e0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 mit mode is re-e
2b5f0 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d nabled by a [COM
2b600 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 MIT] or [ROLLBAC
2b610 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 K]..**.** If cer
2b620 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 tain kinds of er
2b630 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 rors occur on a
2b640 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e statement within
2b650 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 a multi-stateme
2b660 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f nt.** transactio
2b670 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 n (errors includ
2b680 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c ing [SQLITE_FULL
2b690 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ], [SQLITE_IOERR
2b6a0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f ],.** [SQLITE_NO
2b6b0 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 MEM], [SQLITE_BU
2b6c0 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 SY], and [SQLITE
2b6d0 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 _INTERRUPT]) the
2b6e0 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 n the.** transac
2b6f0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f tion might be ro
2b700 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 lled back automa
2b710 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e tically. The on
2b720 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e ly way to.** fin
2b730 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 d out whether SQ
2b740 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c Lite automatical
2b750 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 ly rolled back t
2b760 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 he transaction a
2b770 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 fter.** an error
2b780 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 is to use this
2b790 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
2b7a0 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 If another threa
2b7b0 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 d changes the au
2b7c0 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 tocommit status
2b7d0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
2b7e0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 ** connection wh
2b7f0 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ile this routine
2b800 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 is running, the
2b810 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
2b820 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e ue.** is undefin
2b830 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ed..**.** Requir
2b840 65 6d 65 6e 74 73 3a 20 5b 48 31 32 39 33 31 5d ements: [H12931]
2b850 20 5b 48 31 32 39 33 32 5d 20 5b 48 31 32 39 33 [H12932] [H1293
2b860 33 5d 20 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a 53 3] [H12934].*/.S
2b870 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2b880 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f lite3_get_autoco
2b890 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a mmit(sqlite3*);.
2b8a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2b8b0 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 Find The Databa
2b8c0 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 se Handle Of A P
2b8d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
2b8e0 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36 t {H13120} <S606
2b8f0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
2b900 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 lite3_db_handle
2b910 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2b920 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 s the [database
2b930 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
2b940 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 le.** to which a
2b950 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2b960 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 ment] belongs.
2b970 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f The [database co
2b980 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 nnection].** ret
2b990 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
2b9a0 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 _db_handle is th
2b9b0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
2b9c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 connection] tha
2b9d0 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20 t was the first
2b9e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 argument.** to t
2b9f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 he [sqlite3_prep
2ba00 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 are_v2()] call (
2ba10 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 or its variants)
2ba20 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 that was used t
2ba30 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 o.** create the
2ba40 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 statement in the
2ba50 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a first place..**
2ba60 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
2ba70 3a 20 5b 48 31 33 31 32 33 5d 0a 2a 2f 0a 53 51 : [H13123].*/.SQ
2ba80 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
2ba90 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e *sqlite3_db_han
2baa0 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 dle(sqlite3_stmt
2bab0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2bac0 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 REF: Find the ne
2bad0 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 xt prepared stat
2bae0 65 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c ement {H13140} <
2baf0 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S60600>.**.** Th
2bb00 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 is interface ret
2bb10 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2bb20 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 o the next [prep
2bb30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2bb40 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 after.** pStmt a
2bb50 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
2bb60 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
2bb70 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 nection] pDb. I
2bb80 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a f pStmt is NULL.
2bb90 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 ** then this int
2bba0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2bbb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2bbc0 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 first prepared s
2bbd0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f tatement.** asso
2bbe0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
2bbf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2bc00 69 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 ion pDb. If no
2bc10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2bc20 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 nt.** satisfies
2bc30 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f the conditions o
2bc40 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 f this routine,
2bc50 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e it returns NULL.
2bc60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 .**.** The [data
2bc70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2bc80 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 pointer D in a
2bc90 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
2bca0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c te3_next_stmt(D,
2bcb0 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 S)] must refer t
2bcc0 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 o an open databa
2bcd0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
2bce0 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c and in particul
2bcf0 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 ar must not be a
2bd00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
2bd10 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2bd20 73 3a 20 5b 48 31 33 31 34 33 5d 20 5b 48 31 33 s: [H13143] [H13
2bd30 31 34 36 5d 20 5b 48 31 33 31 34 39 5d 20 5b 48 146] [H13149] [H
2bd40 31 33 31 35 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 13152].*/.SQLITE
2bd50 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 73 74 6d _API sqlite3_stm
2bd60 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f t *sqlite3_next_
2bd70 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 stmt(sqlite3 *pD
2bd80 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 b, sqlite3_stmt
2bd90 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
2bda0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 CAPI3REF: Commit
2bdb0 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f And Rollback No
2bdc0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 tification Callb
2bdd0 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 acks {H12950} <S
2bde0 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 60400>.**.** The
2bdf0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f sqlite3_commit_
2be00 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 hook() interface
2be10 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
2be20 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f lback.** functio
2be30 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 n to be invoked
2be40 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 whenever a trans
2be50 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 action is [COMMI
2be60 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a T | committed]..
2be70 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 ** Any callback
2be80 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 set by a previou
2be90 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 s call to sqlite
2bea0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 3_commit_hook().
2beb0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
2bec0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2bed0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 ion is overridde
2bee0 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 n..** The sqlite
2bef0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
2bf00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
2bf10 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
2bf20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 .** function to
2bf30 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
2bf40 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
2bf50 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c n is [ROLLBACK |
2bf60 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a rolled back]..*
2bf70 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 * Any callback s
2bf80 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 et by a previous
2bf90 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
2bfa0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a _commit_hook().*
2bfb0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 * for the same d
2bfc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2bfd0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e on is overridden
2bfe0 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 ..** The pArg ar
2bff0 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 gument is passed
2c000 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 through to the
2c010 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 callback..** If
2c020 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 the callback on
2c030 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 a commit hook fu
2c040 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e nction returns n
2c050 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e on-zero,.** then
2c060 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 the commit is c
2c070 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 onverted into a
2c080 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 rollback..**.**
2c090 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 If another funct
2c0a0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 ion was previous
2c0b0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 ly registered, i
2c0c0 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 ts.** pArg value
2c0d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f is returned. O
2c0e0 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 therwise NULL is
2c0f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
2c100 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d The callback im
2c110 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 plementation mus
2c120 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
2c130 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
2c140 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
2c150 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
2c160 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 at invoked the c
2c170 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 allback. Any ac
2c180 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 tions.** to modi
2c190 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 fy the database
2c1a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 connection must
2c1b0 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 be deferred unti
2c1c0 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 l after the.** c
2c1d0 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 ompletion of the
2c1e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2c1f0 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 ] call that trig
2c200 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 gered the commit
2c210 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 .** or rollback
2c220 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 hook in the firs
2c230 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 t place..** Note
2c240 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
2c250 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
2c260 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2c270 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
2c280 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
2c290 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
2c2a0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
2c2b0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
2c2c0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
2c2d0 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e Registering a N
2c2e0 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 ULL function dis
2c2f0 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 ables the callba
2c300 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 ck..**.** When t
2c310 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 he commit hook c
2c320 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 allback routine
2c330 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 returns zero, th
2c340 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 e [COMMIT].** op
2c350 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 eration is allow
2c360 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e ed to continue n
2c370 6f 72 6d 61 6c 6c 79 2e 20 20 49 66 20 74 68 65 ormally. If the
2c380 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 commit hook.**
2c390 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
2c3a0 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d , then the [COMM
2c3b0 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 IT] is converted
2c3c0 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 into a [ROLLBAC
2c3d0 4b 5d 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 K]..** The rollb
2c3e0 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f ack hook is invo
2c3f0 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 ked on a rollbac
2c400 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 k that results f
2c410 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 rom a commit.**
2c420 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e hook returning n
2c430 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 on-zero, just as
2c440 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 it would be wit
2c450 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c h any other roll
2c460 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 back..**.** For
2c470 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 the purposes of
2c480 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e this API, a tran
2c490 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 saction is said
2c4a0 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 to have been.**
2c4b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 rolled back if a
2c4c0 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c n explicit "ROLL
2c4d0 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 BACK" statement
2c4e0 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a is executed, or.
2c4f0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 ** an error or c
2c500 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 onstraint causes
2c510 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c an implicit rol
2c520 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a lback to occur..
2c530 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 ** The rollback
2c540 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 callback is not
2c550 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 invoked if a tra
2c560 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 nsaction is.** a
2c570 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c utomatically rol
2c580 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 led back because
2c590 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2c5a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
2c5b0 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 ed..** The rollb
2c5c0 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ack callback is
2c5d0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 not invoked if a
2c5e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a transaction is.
2c5f0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 ** rolled back b
2c600 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 ecause a commit
2c610 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 callback returne
2c620 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c d non-zero..** <
2c630 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 todo> Check on t
2c640 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a his </todo>.**.*
2c650 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b * See also the [
2c660 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
2c670 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ook()] interface
2c680 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
2c690 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31 ents:.** [H12951
2c6a0 5d 20 5b 48 31 32 39 35 32 5d 20 5b 48 31 32 39 ] [H12952] [H129
2c6b0 35 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48 31 53] [H12954] [H1
2c6c0 32 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31 2955].** [H12961
2c6d0 5d 20 5b 48 31 32 39 36 32 5d 20 5b 48 31 32 39 ] [H12962] [H129
2c6e0 36 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a 63] [H12964].*/.
2c6f0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
2c700 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f *sqlite3_commit_
2c710 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 hook(sqlite3*, i
2c720 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f nt(*)(void*), vo
2c730 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 id*);.SQLITE_API
2c740 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 void *sqlite3_r
2c750 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c ollback_hook(sql
2c760 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 ite3*, void(*)(v
2c770 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a oid *), void*);.
2c780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2c790 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 Data Change Not
2c7a0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 ification Callba
2c7b0 63 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 cks {H12970} <S6
2c7c0 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0400>.**.** The
2c7d0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
2c7e0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 ook() interface
2c7f0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
2c800 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a back function.**
2c810 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
2c820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2c830 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 identified by th
2c840 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
2c850 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 .** to be invoke
2c860 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 d whenever a row
2c870 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 is updated, ins
2c880 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 erted or deleted
2c890 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 ..** Any callbac
2c8a0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 k set by a previ
2c8b0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 ous call to this
2c8c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 function.** for
2c8d0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2c8e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2c8f0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a overridden..**.
2c900 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
2c910 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
2c920 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 ter to the funct
2c930 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 ion to invoke wh
2c940 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 en a.** row is u
2c950 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 pdated, inserted
2c960 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 or deleted..**
2c970 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
2c980 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 nt to the callba
2c990 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ck is a copy of
2c9a0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
2c9b0 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 nt.** to sqlite3
2c9c0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a _update_hook()..
2c9d0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 ** The second ca
2c9e0 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 llback argument
2c9f0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 is one of [SQLIT
2ca00 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 E_INSERT], [SQLI
2ca10 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f TE_DELETE],.** o
2ca20 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 r [SQLITE_UPDATE
2ca30 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ], depending on
2ca40 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 the operation th
2ca50 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 at caused the ca
2ca60 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 llback.** to be
2ca70 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 invoked..** The
2ca80 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 third and fourth
2ca90 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
2caa0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 e callback conta
2cab0 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 in pointers to t
2cac0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 he.** database a
2cad0 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f nd table name co
2cae0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 ntaining the aff
2caf0 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 ected row..** Th
2cb00 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b e final callback
2cb10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
2cb20 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 e [rowid] of the
2cb30 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 row..** In the
2cb40 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 case of an updat
2cb50 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b e, this is the [
2cb60 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 rowid] after the
2cb70 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c update takes pl
2cb80 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 ace..**.** The u
2cb90 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f pdate hook is no
2cba0 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 t invoked when i
2cbb0 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 nternal system t
2cbc0 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 ables are.** mod
2cbd0 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 ified (i.e. sqli
2cbe0 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 te_master and sq
2cbf0 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a lite_sequence)..
2cc00 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 63 75 72 **.** In the cur
2cc10 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
2cc20 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 ion, the update
2cc30 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 hook.** is not i
2cc40 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c nvoked when dupl
2cc50 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 ication rows are
2cc60 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 deleted because
2cc70 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f of an.** [ON CO
2cc80 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 NFLICT | ON CONF
2cc90 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c LICT REPLACE] cl
2cca0 61 75 73 65 2e 20 20 4e 6f 72 20 69 73 20 74 68 ause. Nor is th
2ccb0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a e update hook.**
2ccc0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f invoked when ro
2ccd0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 ws are deleted u
2cce0 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 sing the [trunca
2ccf0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d te optimization]
2cd00 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 ..** The excepti
2cd10 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 ons defined in t
2cd20 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 his paragraph mi
2cd30 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 ght change in a
2cd40 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 future.** releas
2cd50 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a e of SQLite..**.
2cd60 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f ** The update ho
2cd70 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ok implementatio
2cd80 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e n must not do an
2cd90 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
2cda0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
2cdb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2cdc0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
2cdd0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e the update hook.
2cde0 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a Any actions.**
2cdf0 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 to modify the d
2ce00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2ce10 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 on must be defer
2ce20 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 red until after
2ce30 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f the.** completio
2ce40 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 n of the [sqlite
2ce50 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 3_step()] call t
2ce60 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 hat triggered th
2ce70 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a e update hook..*
2ce80 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c * Note that [sql
2ce90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2cea0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2ceb0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 step()] both mod
2cec0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 ify their.** dat
2ced0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2cee0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e s for the meanin
2cef0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e g of "modify" in
2cf00 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e this paragraph.
2cf10 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 .**.** If anothe
2cf20 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 r function was p
2cf30 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 reviously regist
2cf40 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 ered, its pArg v
2cf50 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 alue.** is retur
2cf60 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 ned. Otherwise
2cf70 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 NULL is returned
2cf80 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2cf90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
2cfa0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 mmit_hook()] and
2cfb0 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 [sqlite3_rollba
2cfc0 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e ck_hook()].** in
2cfd0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 terfaces..**.**
2cfe0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
2cff0 20 5b 48 31 32 39 37 31 5d 20 5b 48 31 32 39 37 [H12971] [H1297
2d000 33 5d 20 5b 48 31 32 39 37 35 5d 20 5b 48 31 32 3] [H12975] [H12
2d010 39 37 37 5d 20 5b 48 31 32 39 37 39 5d 20 5b 48 977] [H12979] [H
2d020 31 32 39 38 31 5d 20 5b 48 31 32 39 38 33 5d 20 12981] [H12983]
2d030 5b 48 31 32 39 38 36 5d 0a 2a 2f 0a 53 51 4c 49 [H12986].*/.SQLI
2d040 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
2d050 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
2d060 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
2d070 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c void(*)(void *,
2d080 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 int ,char const
2d090 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 *,char const *,s
2d0a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 qlite3_int64),.
2d0b0 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a void*.);../*.**
2d0c0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c CAPI3REF: Enabl
2d0d0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 e Or Disable Sha
2d0e0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 20 red Pager Cache
2d0f0 7b 48 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30 {H10330} <S30900
2d100 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
2d110 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a shared cache}.**
2d120 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
2d130 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
2d140 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 bles the sharing
2d150 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2d160 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 cache.** and sc
2d170 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 hema data struct
2d180 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 ures between [da
2d190 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2d1a0 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d n | connections]
2d1b0 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 .** to the same
2d1c0 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e database. Sharin
2d1d0 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 g is enabled if
2d1e0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 the argument is
2d1f0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 true.** and disa
2d200 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 bled if the argu
2d210 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a ment is false..*
2d220 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 *.** Cache shari
2d230 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e ng is enabled an
2d240 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 d disabled for a
2d250 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 n entire process
2d260 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 ..** This is a c
2d270 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 hange as of SQLi
2d280 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
2d290 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 . In prior versi
2d2a0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a ons of SQLite,.*
2d2b0 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e * sharing was en
2d2c0 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
2d2d0 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 d for each threa
2d2e0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a d separately..**
2d2f0 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 .** The cache sh
2d300 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 aring mode set b
2d310 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 y this interface
2d320 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 effects all sub
2d330 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 sequent.** calls
2d340 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
2d350 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
2d360 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b pen_v2()], and [
2d370 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
2d380 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 ]..** Existing d
2d390 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2d3a0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 ons continue use
2d3b0 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 the sharing mod
2d3c0 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e e.** that was in
2d3d0 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 effect at the t
2d3e0 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 ime they were op
2d3f0 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 ened..**.** Virt
2d400 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f ual tables canno
2d410 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61 t be used with a
2d420 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 shared cache.
2d430 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 When shared.** c
2d440 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c ache is enabled,
2d450 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
2d460 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 eate_module()] A
2d470 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 PI used to regis
2d480 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 ter.** virtual t
2d490 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 ables will alway
2d4a0 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f s return an erro
2d4b0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f r..**.** This ro
2d4c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 utine returns [S
2d4d0 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 QLITE_OK] if sha
2d4e0 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e red cache was en
2d4f0 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
2d500 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c d.** successfull
2d510 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f y. An [error co
2d520 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 de] is returned
2d530 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a otherwise..**.**
2d540 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 Shared cache is
2d550 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
2d560 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d ault. But this m
2d570 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a ight change in.*
2d580 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 * future release
2d590 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 s of SQLite. Ap
2d5a0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
2d5b0 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 care about share
2d5c0 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 d.** cache setti
2d5d0 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 ng should set it
2d5e0 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a explicitly..**.
2d5f0 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 ** See Also: [S
2d600 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 QLite Shared-Cac
2d610 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 he Mode].**.** R
2d620 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 equirements: [H1
2d630 30 33 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 0331] [H10336] [
2d640 48 31 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d H10337] [H10339]
2d650 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2d660 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c nt sqlite3_enabl
2d670 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 e_shared_cache(i
2d680 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
2d690 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 3REF: Attempt To
2d6a0 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 Free Heap Memor
2d6b0 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 32 y {H17340} <S302
2d6c0 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 20>.**.** The sq
2d6d0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 lite3_release_me
2d6e0 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 mory() interface
2d6f0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 attempts to fre
2d700 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 e N bytes.** of
2d710 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 heap memory by d
2d720 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d eallocating non-
2d730 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 essential memory
2d740 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 allocations.**
2d750 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 held by the data
2d760 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 base library. {E
2d770 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 ND} Memory used
2d780 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 to cache databa
2d790 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 se.** pages to i
2d7a0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e mprove performan
2d7b0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 ce is an example
2d7c0 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 of non-essentia
2d7d0 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c l memory..** sql
2d7e0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
2d7f0 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 ory() returns th
2d800 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2d810 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 s actually freed
2d820 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 ,.** which might
2d830 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 be more or less
2d840 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 than the amount
2d850 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a requested..**.*
2d860 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 * Requirements:
2d870 5b 48 31 37 33 34 31 5d 20 5b 48 31 37 33 34 32 [H17341] [H17342
2d880 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
2d890 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 int sqlite3_rele
2d8a0 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b ase_memory(int);
2d8b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2d8c0 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 : Impose A Limit
2d8d0 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 48 On Heap Size {H
2d8e0 31 37 33 35 30 7d 20 3c 53 33 30 32 32 30 3e 0a 17350} <S30220>.
2d8f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
2d900 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
2d910 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c t() interface pl
2d920 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 aces a "soft" li
2d930 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d mit.** on the am
2d940 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d ount of heap mem
2d950 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 ory that may be
2d960 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
2d970 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e ite..** If an in
2d980 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f ternal allocatio
2d990 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 74 n is requested t
2d9a0 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 hat would exceed
2d9b0 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 the.** soft hea
2d9c0 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 p limit, [sqlite
2d9d0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
2d9e0 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ()] is invoked o
2d9f0 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 ne or.** more ti
2da00 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 mes to free up s
2da10 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 ome space before
2da20 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 the allocation
2da30 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a is performed..**
2da40 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 .** The limit is
2da50 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 called "soft",
2da60 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 because if [sqli
2da70 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2da80 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 ry()].** cannot
2da90 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 free sufficient
2daa0 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e memory to preven
2dab0 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d t the limit from
2dac0 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c being exceeded,
2dad0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 .** the memory i
2dae0 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 s allocated anyw
2daf0 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 ay and the curre
2db00 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f nt operation pro
2db10 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e ceeds..**.** A n
2db20 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 egative or zero
2db30 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e value for N mean
2db40 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 s that there is
2db50 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d no soft heap lim
2db60 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 it and.** [sqlit
2db70 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
2db80 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 y()] will only b
2db90 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 e called when me
2dba0 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65 mory is exhauste
2dbb0 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c d..** The defaul
2dbc0 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 t value for the
2dbd0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
2dbe0 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 is zero..**.** S
2dbf0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 QLite makes a be
2dc00 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e st effort to hon
2dc10 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 or the soft heap
2dc20 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 limit..** But i
2dc30 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 f the soft heap
2dc40 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 limit cannot be
2dc50 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 honored, executi
2dc60 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 on will.** conti
2dc70 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f nue without erro
2dc80 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f r or notificatio
2dc90 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 20 n. This is why
2dca0 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 the limit is.**
2dcb0 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 called a "soft"
2dcc0 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 limit. It is ad
2dcd0 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a visory only..**.
2dce0 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 ** Prior to SQLi
2dcf0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
2dd00 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f , this routine o
2dd10 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 nly constrained
2dd20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c the memory.** al
2dd30 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e located by a sin
2dd40 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 gle thread - the
2dd50 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
2dd60 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 which this routi
2dd70 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 ne.** runs. Beg
2dd80 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 inning with SQLi
2dd90 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
2dda0 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 , the soft heap
2ddb0 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c limit is.** appl
2ddc0 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 ied to all threa
2ddd0 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 ds. The value sp
2dde0 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 ecified for the
2ddf0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a soft heap limit.
2de00 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 ** is an upper b
2de10 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 ound on the tota
2de20 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
2de30 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 ion for all thre
2de40 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 ads. In.** versi
2de50 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 on 3.5.0 there i
2de60 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 s no mechanism f
2de70 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 or limiting the
2de80 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a heap usage for.*
2de90 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 * individual thr
2dea0 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 eads..**.** Requ
2deb0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
2dec0 36 33 35 31 5d 20 5b 48 31 36 33 35 32 5d 20 5b 6351] [H16352] [
2ded0 48 31 36 33 35 33 5d 20 5b 48 31 36 33 35 34 5d H16353] [H16354]
2dee0 20 5b 48 31 36 33 35 35 5d 20 5b 48 31 36 33 35 [H16355] [H1635
2def0 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 8].*/.SQLITE_API
2df00 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f void sqlite3_so
2df10 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e ft_heap_limit(in
2df20 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2df30 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 REF: Extract Met
2df40 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f adata About A Co
2df50 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 lumn Of A Table
2df60 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 33 30 30 {H12850} <S60300
2df70 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
2df80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 tine returns met
2df90 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 adata about a sp
2dfa0 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 ecific column of
2dfb0 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 a specific.** d
2dfc0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 atabase table ac
2dfd0 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 cessible using t
2dfe0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
2dff0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a nection] handle.
2e000 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ** passed as the
2e010 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 first function
2e020 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
2e030 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 The column is id
2e040 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
2e050 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e second, third an
2e060 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 d fourth paramet
2e070 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 ers to.** this f
2e080 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 unction. The sec
2e090 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
2e0a0 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 either the name
2e0b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2e0c0 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 .** (i.e. "main"
2e0d0 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 , "temp" or an a
2e0e0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
2e0f0 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 ) containing the
2e100 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 specified.** ta
2e110 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 ble or NULL. If
2e120 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e it is NULL, then
2e130 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 all attached da
2e140 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 tabases are sear
2e150 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ched.** for the
2e160 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 table using the
2e170 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 same algorithm u
2e180 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 sed by the datab
2e190 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a ase engine to.**
2e1a0 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 resolve unquali
2e1b0 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 fied table refer
2e1c0 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ences..**.** The
2e1d0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
2e1e0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
2e1f0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 this function ar
2e200 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 e the table and
2e210 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f column.** name o
2e220 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f f the desired co
2e230 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 lumn, respective
2e240 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 ly. Neither of t
2e250 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a hese parameters.
2e260 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a ** may be NULL..
2e270 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 **.** Metadata i
2e280 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 s returned by wr
2e290 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d iting to the mem
2e2a0 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 ory locations pa
2e2b0 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a ssed as the 5th.
2e2c0 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e ** and subsequen
2e2d0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
2e2e0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 this function. A
2e2f0 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 ny of these argu
2e300 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 ments may be.**
2e310 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 NULL, in which c
2e320 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f ase the correspo
2e330 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 nding element of
2e340 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 metadata is omi
2e350 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f tted..**.** <blo
2e360 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 ckquote>.** <tab
2e370 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a le border="1">.*
2e380 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d * <tr><th> Param
2e390 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 eter <th> Output
2e3a0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 <br>Type <th> D
2e3b0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a escription.**.**
2e3c0 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 <tr><td> 5th <t
2e3d0 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c d> const char* <
2e3e0 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a td> Data type.**
2e3f0 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 <tr><td> 6th <t
2e400 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c d> const char* <
2e410 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 td> Name of defa
2e420 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 ult collation se
2e430 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 quence.** <tr><t
2e440 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 d> 7th <td> int
2e450 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 <td> Tru
2e460 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 e if column has
2e470 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 a NOT NULL const
2e480 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 raint.** <tr><td
2e490 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 > 8th <td> int
2e4a0 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 <td> True
2e4b0 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 if column is pa
2e4c0 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 rt of the PRIMAR
2e4d0 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 Y KEY.** <tr><td
2e4e0 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 > 9th <td> int
2e4f0 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 <td> True
2e500 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 if column is [A
2e510 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a UTOINCREMENT].**
2e520 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 </table>.** </b
2e530 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
2e540 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e The memory poin
2e550 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 ted to by the ch
2e560 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 aracter pointers
2e570 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 returned for th
2e580 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e e.** declaration
2e590 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 type and collat
2e5a0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 ion sequence is
2e5b0 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c valid only until
2e5c0 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c the next.** cal
2e5d0 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 l to any SQLite
2e5e0 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a API function..**
2e5f0 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 .** If the speci
2e600 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 fied table is ac
2e610 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 tually a view, a
2e620 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
2e630 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
2e640 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 * If the specifi
2e650 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f ed column is "ro
2e660 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 wid", "oid" or "
2e670 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a _rowid_" and an.
2e680 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d ** [INTEGER PRIM
2e690 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 ARY KEY] column
2e6a0 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 has been explici
2e6b0 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 tly declared, th
2e6c0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a en the output.**
2e6d0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
2e6e0 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c set for the expl
2e6f0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 icitly declared
2e700 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 column. If there
2e710 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 is no.** explic
2e720 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 itly declared [I
2e730 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
2e740 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e EY] column, then
2e750 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 the output.** p
2e760 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 arameters are se
2e770 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
2e780 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 .** <pre>.**
2e790 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 data type: "INT
2e7a0 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c EGER".** col
2e7b0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a lation sequence:
2e7c0 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 "BINARY".**
2e7d0 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 not null: 0.**
2e7e0 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a primary key:
2e7f0 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 1.** auto i
2e800 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c ncrement: 0.** <
2e810 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 /pre>.**.** This
2e820 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f function may lo
2e830 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 ad one or more s
2e840 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 chemas from data
2e850 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 base files. If a
2e860 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 n.** error occur
2e870 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 s during this pr
2e880 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 ocess, or if the
2e890 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 requested table
2e8a0 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 or column.** ca
2e8b0 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 nnot be found, a
2e8c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
2e8d0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 s returned and a
2e8e0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
2e8f0 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b left.** in the [
2e900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2e910 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 ion] (to be retr
2e920 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 ieved using sqli
2e930 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a te3_errmsg())..*
2e940 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 *.** This API is
2e950 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
2e960 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 if the library w
2e970 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
2e980 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
2e990 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 ENABLE_COLUMN_ME
2e9a0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f TADATA] C-prepro
2e9b0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 cessor symbol de
2e9c0 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 fined..*/.SQLITE
2e9d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2e9e0 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 _table_column_me
2e9f0 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 tadata(. sqlite
2ea00 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2ea10 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 /* Connect
2ea20 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ion handle */.
2ea30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e const char *zDbN
2ea40 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 ame, /* D
2ea50 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 atabase name or
2ea60 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 NULL */. const
2ea70 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 char *zTableName
2ea80 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e , /* Table n
2ea90 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ame */. const c
2eaa0 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 har *zColumnName
2eab0 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e , /* Column n
2eac0 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f ame */. char co
2ead0 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 nst **pzDataType
2eae0 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 , /* OUTPUT:
2eaf0 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 Declared data ty
2eb00 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e pe */. char con
2eb10 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 st **pzCollSeq,
2eb20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 /* OUTPUT: C
2eb30 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
2eb40 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 e name */. int
2eb50 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 *pNotNull,
2eb60 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 /* OUTPU
2eb70 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e T: True if NOT N
2eb80 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 ULL constraint e
2eb90 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a xists */. int *
2eba0 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 pPrimaryKey,
2ebb0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 /* OUTPUT
2ebc0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e : True if column
2ebd0 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 part of PK */.
2ebe0 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 int *pAutoinc
2ebf0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2ec00 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 OUTPUT: True if
2ec10 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 column is auto-i
2ec20 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a ncrement */.);..
2ec30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2ec40 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f Load An Extensio
2ec50 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 30 35 n {H12600} <S205
2ec60 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 00>.**.** This i
2ec70 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 nterface loads a
2ec80 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 n SQLite extensi
2ec90 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 on library from
2eca0 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a the named file..
2ecb0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d 20 54 **.** {H12601} T
2ecc0 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f he sqlite3_load_
2ecd0 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 extension() inte
2ece0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
2ecf0 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 20 20 o load an.**
2ed00 20 20 20 20 20 20 53 51 4c 69 74 65 20 65 78 74 SQLite ext
2ed10 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 ension library c
2ed20 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 ontained in the
2ed30 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a file zFile..**.*
2ed40 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65 20 65 * {H12602} The e
2ed50 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 ntry point is zP
2ed60 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 roc..**.** {H126
2ed70 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 03} zProc may be
2ed80 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 0, in which cas
2ed90 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 e the name of th
2eda0 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a e entry point.**
2edb0 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c defaul
2edc0 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 ts to "sqlite3_e
2edd0 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a xtension_init"..
2ede0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d 20 54 **.** {H12604} T
2edf0 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f he sqlite3_load_
2ee00 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 extension() inte
2ee10 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 rface shall retu
2ee20 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b rn.** [
2ee30 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
2ee40 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 ccess and [SQLIT
2ee50 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 E_ERROR] if some
2ee60 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 thing goes wrong
2ee70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 35 7d ..**.** {H12605}
2ee80 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 If an error occ
2ee90 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 urs and pzErrMsg
2eea0 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 is not 0, then
2eeb0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2eec0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 [sqlite3_load_ex
2eed0 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 tension()] inter
2eee0 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d face shall attem
2eef0 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 pt to.**
2ef00 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 fill *pzErrMsg
2ef10 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 with error mess
2ef20 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 age text stored
2ef30 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 in memory.**
2ef40 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 obtained f
2ef50 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
2ef60 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 20 54 loc()]. {END} T
2ef70 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
2ef80 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
2ef90 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 should free this
2efa0 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 memory by calli
2efb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ng [sqlite3_free
2efc0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ()]..**.** {H126
2efd0 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 06} Extension lo
2efe0 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e ading must be en
2eff0 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 abled using.**
2f000 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2f010 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 _enable_load_ext
2f020 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 ension()] prior
2f030 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 to calling this
2f040 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 API,.**
2f050 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 otherwise an er
2f060 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 ror will be retu
2f070 72 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f rned..*/.SQLITE_
2f080 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2f090 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a load_extension(.
2f0a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2f0b0 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 /* Load
2f0c0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e the extension in
2f0d0 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 to this database
2f0e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 connection */.
2f0f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 const char *zFi
2f100 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f le, /* Name o
2f110 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 f the shared lib
2f120 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 rary containing
2f130 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 extension */. c
2f140 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 onst char *zProc
2f150 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f , /* Entry po
2f160 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 int. Derived fr
2f170 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f om zFile if 0 */
2f180 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d . char **pzErrM
2f190 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 sg /* Put
2f1a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 error message he
2f1b0 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 re if not 0 */.)
2f1c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2f1d0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 F: Enable Or Dis
2f1e0 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c able Extension L
2f1f0 6f 61 64 69 6e 67 20 7b 48 31 32 36 32 30 7d 20 oading {H12620}
2f200 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 <S20500>.**.** S
2f210 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e o as not to open
2f220 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 security holes
2f230 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 in older applica
2f240 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a tions that are.*
2f250 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 * unprepared to
2f260 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 deal with extens
2f270 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 ion loading, and
2f280 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 as a means of d
2f290 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 isabling.** exte
2f2a0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 nsion loading wh
2f2b0 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 ile evaluating u
2f2c0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c ser-entered SQL,
2f2d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 the following A
2f2e0 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 PI.** is provide
2f2f0 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 d to turn the [s
2f300 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
2f310 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 nsion()] mechani
2f320 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a sm on and off..*
2f330 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c *.** Extension l
2f340 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 oading is off by
2f350 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 default. See ti
2f360 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a cket #1863..**.*
2f370 2a 20 7b 48 31 32 36 32 31 7d 20 43 61 6c 6c 20 * {H12621} Call
2f380 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 the sqlite3_enab
2f390 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
2f3a0 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 n() routine with
2f3b0 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 20 20 20 onoff==1.**
2f3c0 20 20 20 20 20 20 74 6f 20 74 75 72 6e 20 65 78 to turn ex
2f3d0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 tension loading
2f3e0 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 on and call it w
2f3f0 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 ith onoff==0 to
2f400 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 turn.**
2f410 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 it back off aga
2f420 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 in..**.** {H1262
2f430 32 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 2} Extension loa
2f440 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 ding is off by d
2f450 65 66 61 75 6c 74 2e 0a 2a 2f 0a 53 51 4c 49 54 efault..*/.SQLIT
2f460 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2f470 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 3_enable_load_ex
2f480 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 tension(sqlite3
2f490 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b *db, int onoff);
2f4a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2f4b0 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 : Automatically
2f4c0 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f Load An Extensio
2f4d0 6e 73 20 7b 48 31 32 36 34 30 7d 20 3c 53 32 30 ns {H12640} <S20
2f4e0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 500>.**.** This
2f4f0 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b API can be invok
2f500 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 ed at program st
2f510 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 artup in order t
2f520 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e o register.** on
2f530 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 e or more static
2f540 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 ally linked exte
2f550 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c nsions that will
2f560 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a be available.**
2f570 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 to all new [dat
2f580 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2f590 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 s]. {END}.**.**
2f5a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f This routine sto
2f5b0 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f res a pointer to
2f5c0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 the extension i
2f5d0 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 n an array that
2f5e0 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 is.** obtained f
2f5f0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
2f600 6c 6f 63 28 29 5d 2e 20 20 49 66 20 79 6f 75 20 loc()]. If you
2f610 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 run a memory lea
2f620 6b 20 63 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 k checker.** on
2f630 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 your program and
2f640 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 it reports a le
2f650 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 ak because of th
2f660 69 73 20 61 72 72 61 79 2c 20 69 6e 76 6f 6b 65 is array, invoke
2f670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
2f680 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f et_auto_extensio
2f690 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 73 68 n()] prior to sh
2f6a0 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 utdown to free t
2f6b0 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a he memory..**.**
2f6c0 20 7b 48 31 32 36 34 31 7d 20 54 68 69 73 20 66 {H12641} This f
2f6d0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
2f6e0 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 s an extension e
2f6f0 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 ntry point that
2f700 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 is.** a
2f710 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 utomatically inv
2f720 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 oked whenever a
2f730 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f new [database co
2f740 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 nnection].**
2f750 20 20 20 20 20 20 69 73 20 6f 70 65 6e 65 64 20 is opened
2f760 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f using [sqlite3_o
2f770 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
2f780 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 _open16()],.**
2f790 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 or [sqli
2f7a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a te3_open_v2()]..
2f7b0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 7d 20 44 **.** {H12642} D
2f7c0 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 uplicate extensi
2f7d0 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64 ons are detected
2f7e0 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 so calling this
2f7f0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 routine.**
2f800 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 20 74 69 multiple ti
2f810 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d mes with the sam
2f820 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 e extension is h
2f830 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b armless..**.** {
2f840 48 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75 H12643} This rou
2f850 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f tine stores a po
2f860 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 inter to the ext
2f870 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 ension in an arr
2f880 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ay.** t
2f890 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 hat is obtained
2f8a0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
2f8b0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b lloc()]..**.** {
2f8c0 48 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 H12644} Automati
2f8d0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 c extensions app
2f8e0 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 ly across all th
2f8f0 72 65 61 64 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 reads..*/.SQLITE
2f900 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2f910 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 _auto_extension(
2f920 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 void (*xEntryPoi
2f930 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a nt)(void));../*.
2f940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
2f950 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 et Automatic Ext
2f960 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b ension Loading {
2f970 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30 3e H12660} <S20500>
2f980 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
2f990 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c tion disables al
2f9a0 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 l previously reg
2f9b0 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 istered automati
2f9c0 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e c.** extensions.
2f9d0 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f 65 {END} It undoe
2f9e0 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 s the effect of
2f9f0 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 all prior.** [sq
2fa00 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e lite3_auto_exten
2fa10 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a 2a sion()] calls..*
2fa20 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54 68 *.** {H12661} Th
2fa30 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 is function disa
2fa40 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 bles all previou
2fa50 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a 2a sly registered.*
2fa60 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d * autom
2fa70 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e atic extensions.
2fa80 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d 20 .**.** {H12662}
2fa90 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 This function di
2faa0 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 sables automatic
2fab0 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 extensions in a
2fac0 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 53 ll threads..*/.S
2fad0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
2fae0 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 qlite3_reset_aut
2faf0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 o_extension(void
2fb00 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 );../*.****** EX
2fb10 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 PERIMENTAL - sub
2fb20 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 ject to change w
2fb30 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a ithout notice **
2fb40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a ************.**.
2fb50 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 ** The interface
2fb60 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d to the virtual-
2fb70 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 table mechanism
2fb80 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e is currently con
2fb90 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 sidered.** to be
2fba0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 experimental.
2fbb0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 The interface mi
2fbc0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e ght change in in
2fbd0 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e compatible ways.
2fbe0 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 .** If this is a
2fbf0 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 problem for you
2fc00 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 , do not use the
2fc10 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 interface at th
2fc20 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 is time..**.** W
2fc30 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d hen the virtual-
2fc40 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 table mechanism
2fc50 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 stabilizes, we w
2fc60 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a ill declare the.
2fc70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 ** interface fix
2fc80 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 ed, support it i
2fc90 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 ndefinitely, and
2fca0 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d remove this com
2fcb0 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 ment..*/../*.**
2fcc0 53 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 Structures used
2fcd0 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 by the virtual t
2fce0 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a able interface.*
2fcf0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
2fd00 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 sqlite3_vtab sq
2fd10 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 lite3_vtab;.type
2fd20 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
2fd30 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 e3_index_info sq
2fd40 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f lite3_index_info
2fd50 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 ;.typedef struct
2fd60 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
2fd70 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 rsor sqlite3_vta
2fd80 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 b_cursor;.typede
2fd90 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
2fda0 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f _module sqlite3_
2fdb0 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 module;../*.** C
2fdc0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c API3REF: Virtual
2fdd0 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 48 Table Object {H
2fde0 31 38 30 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18000} <S20400>.
2fdf0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
2fe00 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 ite3_module {vir
2fe10 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
2fe20 65 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 e}.** EXPERIMENT
2fe30 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 AL.**.** This st
2fe40 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d ructure, sometim
2fe50 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76 es called a a "v
2fe60 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
2fe70 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 ule", .** define
2fe80 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 s the implementa
2fe90 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 tion of a [virtu
2fea0 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a al tables]. .**
2feb0 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 This structure
2fec0 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 consists mostly
2fed0 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 of methods for t
2fee0 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a he module..**.**
2fef0 20 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 A virtual table
2ff00 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74 module is creat
2ff10 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e ed by filling in
2ff20 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a a persistent.**
2ff30 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
2ff40 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 s structure and
2ff50 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 passing a pointe
2ff60 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e r to that instan
2ff70 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 ce.** to [sqlite
2ff80 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 3_create_module(
2ff90 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 )] or [sqlite3_c
2ffa0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 reate_module_v2(
2ffb0 29 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 67 69 73 )]..** The regis
2ffc0 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 tration remains
2ffd0 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 valid until it i
2ffe0 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 s replaced by a
2fff0 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 different.** mod
30000 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ule or until the
30010 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
30020 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 ction] closes.
30030 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f The content.** o
30040 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 f this structure
30050 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 must not change
30060 20 77 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 while it is reg
30070 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 istered with.**
30080 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e any database con
30090 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 nection..*/.stru
300a0 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c ct sqlite3_modul
300b0 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 e {. int iVersi
300c0 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 on;. int (*xCre
300d0 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 ate)(sqlite3*, v
300e0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 oid *pAux,.
300f0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
30100 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a gc, const char *
30110 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 const*argv,.
30120 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 sqlit
30130 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 e3_vtab **ppVTab
30140 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 , char**);. int
30150 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c (*xConnect)(sql
30160 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 ite3*, void *pAu
30170 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 x,.
30180 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 int argc, cons
30190 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 t char *const*ar
301a0 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 gv,.
301b0 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 sqlite3_vtab
301c0 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a **ppVTab, char**
301d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 );. int (*xBest
301e0 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 Index)(sqlite3_v
301f0 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 tab *pVTab, sqli
30200 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 te3_index_info*)
30210 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f ;. int (*xDisco
30220 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 nnect)(sqlite3_v
30230 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
30240 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 nt (*xDestroy)(s
30250 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
30260 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 ab);. int (*xOp
30270 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 en)(sqlite3_vtab
30280 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 *pVTab, sqlite3
30290 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 _vtab_cursor **p
302a0 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 pCursor);. int
302b0 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
302c0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 3_vtab_cursor*);
302d0 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 . int (*xFilter
302e0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
302f0 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e ursor*, int idxN
30300 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a um, const char *
30310 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 idxStr,.
30320 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 int argc
30330 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 , sqlite3_value
30340 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 **argv);. int (
30350 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f *xNext)(sqlite3_
30360 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 vtab_cursor*);.
30370 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c int (*xEof)(sql
30380 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
30390 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c *);. int (*xCol
303a0 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 umn)(sqlite3_vta
303b0 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 b_cursor*, sqlit
303c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
303d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 );. int (*xRowi
303e0 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f d)(sqlite3_vtab_
303f0 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 cursor*, sqlite3
30400 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b _int64 *pRowid);
30410 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 . int (*xUpdate
30420 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
30430 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 , int, sqlite3_v
30440 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 alue **, sqlite3
30450 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 _int64 *);. int
30460 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 (*xBegin)(sqlit
30470 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
30480 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 . int (*xSync)(
30490 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
304a0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 Tab);. int (*xC
304b0 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 ommit)(sqlite3_v
304c0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
304d0 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 nt (*xRollback)(
304e0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
304f0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Tab);. int (*xF
30500 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c indFunction)(sql
30510 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
30520 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 , int nArg, cons
30530 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 t char *zName,.
30540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
30550 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 void (**px
30560 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
30570 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
30580 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 e3_value**),.
30590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
305a0 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 void **ppArg
305b0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 );. int (*xRena
305c0 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 me)(sqlite3_vtab
305d0 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 *pVtab, const c
305e0 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a har *zNew);.};..
305f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
30600 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e Virtual Table In
30610 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 dexing Informati
30620 6f 6e 20 7b 48 31 38 31 30 30 7d 20 3c 53 32 30 on {H18100} <S20
30630 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 400>.** KEYWORDS
30640 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f : sqlite3_index_
30650 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 49 4d 45 info.** EXPERIME
30660 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 NTAL.**.** The s
30670 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 qlite3_index_inf
30680 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 o structure and
30690 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65 its substructure
306a0 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 s is used to.**
306b0 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e pass information
306c0 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 into and receiv
306d0 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d e the reply from
306e0 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 the [xBestIndex
306f0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 ].** method of a
30700 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
30710 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 module]. The fi
30720 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 elds under **Inp
30730 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a uts** are the.**
30740 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 inputs to xBest
30750 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 Index and are re
30760 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 ad-only. xBestI
30770 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 ndex inserts its
30780 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f .** results into
30790 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a the **Outputs**
307a0 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 fields..**.** T
307b0 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d he aConstraint[]
307c0 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 array records W
307d0 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 HERE clause cons
307e0 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 traints of the f
307f0 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e orm:.**.** <pre>
30800 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f column OP expr</
30810 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 pre>.**.** where
30820 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 OP is =, <,
30830 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 <=, >, or
30840 26 67 74 3b 3d 2e 20 20 54 68 65 20 70 61 72 74 >=. The part
30850 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 icular operator
30860 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 is.** stored in
30870 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 aConstraint[].op
30880 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 . The index of
30890 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 the column is st
308a0 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 ored in.** aCons
308b0 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e traint[].iColumn
308c0 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d . aConstraint[]
308d0 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 .usable is TRUE
308e0 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f if the.** expr o
308f0 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 n the right-hand
30900 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 side can be eva
30910 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 luated (and thus
30920 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a the constraint.
30930 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e ** is usable) an
30940 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 d false if it ca
30950 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nnot..**.** The
30960 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 optimizer automa
30970 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 tically inverts
30980 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 terms of the for
30990 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d m "expr OP colum
309a0 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 n".** and makes
309b0 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 other simplifica
309c0 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 tions to the WHE
309d0 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 RE clause in an
309e0 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 attempt to.** ge
309f0 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 t as many WHERE
30a00 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 clause terms int
30a10 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e o the form shown
30a20 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 above as possib
30a30 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 le..** The aCons
30a40 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f traint[] array o
30a50 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 nly reports WHER
30a60 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 E clause terms i
30a70 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a n the correct.**
30a80 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 form that refer
30a90 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c to the particul
30aa0 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ar virtual table
30ab0 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a being queried..
30ac0 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f **.** Informatio
30ad0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 n about the ORDE
30ae0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 R BY clause is s
30af0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 tored in aOrderB
30b00 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 y[]..** Each ter
30b10 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 m of aOrderBy re
30b20 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f cords a column o
30b30 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 f the ORDER BY c
30b40 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 lause..**.** The
30b50 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 [xBestIndex] me
30b60 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 thod must fill a
30b70 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b ConstraintUsage[
30b80 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 ] with informati
30b90 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 on.** about what
30ba0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 parameters to p
30bb0 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 ass to xFilter.
30bc0 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 If argvIndex>0
30bd0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 then.** the righ
30be0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 t-hand side of t
30bf0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
30c00 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 aConstraint[] i
30c10 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 s evaluated.** a
30c20 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 nd becomes the a
30c30 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 rgvIndex-th entr
30c40 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 y in argv. If a
30c50 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b ConstraintUsage[
30c60 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 ].omit.** is tru
30c70 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 e, then the cons
30c80 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 traint is assume
30c90 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 d to be fully ha
30ca0 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 ndled by the.**
30cb0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e virtual table an
30cc0 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 d is not checked
30cd0 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 again by SQLite
30ce0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e ..**.** The idxN
30cf0 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 um and idxPtr va
30d00 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 lues are recorde
30d10 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 d and passed int
30d20 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 o the.** [xFilte
30d30 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5b 73 r] method..** [s
30d40 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 qlite3_free()] i
30d50 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 s used to free i
30d60 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c dxPtr if and onl
30d70 79 20 69 66 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 y iff.** needToF
30d80 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 reeIdxPtr is tru
30d90 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 e..**.** The ord
30da0 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 erByConsumed mea
30db0 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 ns that output f
30dc0 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 rom [xFilter]/[x
30dd0 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 Next] will occur
30de0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 in.** the corre
30df0 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 ct order to sati
30e00 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 sfy the ORDER BY
30e10 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 clause so that
30e20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 no separate.** s
30e30 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 orting step is r
30e40 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 equired..**.** T
30e50 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 he estimatedCost
30e60 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 value is an est
30e70 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 imate of the cos
30e80 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a t of doing the.*
30e90 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f * particular loo
30ea0 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 kup. A full sca
30eb0 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 n of a table wit
30ec0 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 h N entries shou
30ed0 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 ld have.** a cos
30ee0 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 t of N. A binar
30ef0 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 y search of a ta
30f00 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 ble of N entries
30f10 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a should have a.*
30f20 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 * cost of approx
30f30 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a imately log(N)..
30f40 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
30f50 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 3_index_info {.
30f60 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 /* Inputs */.
30f70 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b int nConstraint;
30f80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
30f90 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 mber of entries
30fa0 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a in aConstraint *
30fb0 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 /. struct sqlit
30fc0 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 e3_index_constra
30fd0 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 int {. int i
30fe0 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 Column;
30ff0 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f /* Column o
31000 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 n left-hand side
31010 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a of constraint *
31020 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 /. unsigned
31030 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 char op;
31040 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f /* Constraint o
31050 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 perator */.
31060 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 unsigned char us
31070 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 able; /* Tru
31080 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 e if this constr
31090 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a aint is usable *
310a0 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d /. int iTerm
310b0 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 Offset;
310c0 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 /* Used interna
310d0 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 lly - xBestIndex
310e0 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a should ignore *
310f0 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 /. } *aConstrai
31100 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f nt; /
31110 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 * Table of WHERE
31120 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 clause constrai
31130 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 nts */. int nOr
31140 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 derBy;
31150 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
31160 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 terms in the OR
31170 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f DER BY clause */
31180 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 . struct sqlite
31190 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 3_index_orderby
311a0 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 {. int iColu
311b0 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 mn;
311c0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 /* Column numbe
311d0 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e r */. unsign
311e0 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 ed char desc;
311f0 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 /* True for
31200 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 DESC. False for
31210 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f ASC. */. } *aO
31220 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 rderBy;
31230 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 /* The ORD
31240 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a ER BY clause */.
31250 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a /* Outputs */.
31260 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 struct sqlite3
31270 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e _index_constrain
31280 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e t_usage {. in
31290 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 t argvIndex;
312a0 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c /* if >0,
312b0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 constraint is p
312c0 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 art of argv to x
312d0 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e Filter */. un
312e0 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 signed char omit
312f0 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 ; /* Do not
31300 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 code a test for
31310 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 this constraint
31320 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 */. } *aConstr
31330 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 aintUsage;. int
31340 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 idxNum;
31350 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
31360 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 r used to identi
31370 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a fy the index */.
31380 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 char *idxStr;
31390 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
313a0 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 String, possibly
313b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
313c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f qlite3_malloc */
313d0 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 . int needToFre
313e0 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a eIdxStr; /*
313f0 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69 Free idxStr usi
31400 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ng sqlite3_free(
31410 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 ) if true */. i
31420 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d nt orderByConsum
31430 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 ed; /* Tru
31440 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 e if output is a
31450 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a lready ordered *
31460 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d /. double estim
31470 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f atedCost; /
31480 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 * Estimated cost
31490 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 of using this i
314a0 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 ndex */.};.#defi
314b0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
314c0 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 CONSTRAINT_EQ
314d0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
314e0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 E_INDEX_CONSTRAI
314f0 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 NT_GT 4.#defi
31500 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
31510 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 CONSTRAINT_LE
31520 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 8.#define SQLIT
31530 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 E_INDEX_CONSTRAI
31540 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 NT_LT 16.#def
31550 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
31560 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 _CONSTRAINT_GE
31570 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 32.#define SQL
31580 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
31590 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f AINT_MATCH 64../
315a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
315b0 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 egister A Virtua
315c0 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e l Table Implemen
315d0 74 61 74 69 6f 6e 20 7b 48 31 38 32 30 30 7d 20 tation {H18200}
315e0 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 <S20400>.** EXPE
315f0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
31600 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 his routine is u
31610 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 sed to register
31620 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 a new [virtual t
31630 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d able module] nam
31640 65 2e 0a 2a 2a 20 4d 6f 64 75 6c 65 20 6e 61 6d e..** Module nam
31650 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 es must be regis
31660 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 tered before.**
31670 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b creating a new [
31680 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 virtual table] u
31690 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 2c sing the module,
316a0 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 or before using
316b0 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e a.** preexistin
316c0 67 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 g [virtual table
316d0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 ] for the module
316e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 6f 64 75 ..**.** The modu
316f0 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 le name is regis
31700 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 tered on the [da
31710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
31720 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 n] specified.**
31730 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 by the first par
31740 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6e 61 6d ameter. The nam
31750 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 e of the module
31760 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 is given by the
31770 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
31780 65 74 65 72 2e 20 20 54 68 65 20 74 68 69 72 64 eter. The third
31790 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
317a0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 pointer to.** th
317b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
317c0 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c of the [virtual
317d0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 table module].
317e0 20 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 The fourth.**
317f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 parameter is an
31800 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 arbitrary client
31810 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 data pointer th
31820 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 at is passed thr
31830 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 ough.** into the
31840 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b [xCreate] and [
31850 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 xConnect] method
31860 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c s of the virtual
31870 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a table module.**
31880 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 when a new virt
31890 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 ual table is be
318a0 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 being created or
318b0 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a reinitialized..
318c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
318d0 66 61 63 65 20 68 61 73 20 65 78 61 63 74 6c 79 face has exactly
318e0 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 the same effect
318f0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 5b as calling.** [
31900 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
31910 6f 64 75 6c 65 5f 76 32 28 29 5d 20 77 69 74 68 odule_v2()] with
31920 20 61 20 4e 55 4c 4c 20 63 6c 69 65 6e 74 20 64 a NULL client d
31930 61 74 61 20 64 65 73 74 72 75 63 74 6f 72 2e 0a ata destructor..
31940 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
31950 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
31960 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 L int sqlite3_cr
31970 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 eate_module(. s
31980 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
31990 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c /* SQL
319a0 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ite connection t
319b0 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c o register modul
319c0 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 e with */. cons
319d0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 t char *zName,
319e0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
319f0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a f the module */.
31a00 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f const sqlite3_
31a10 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 module *p, /*
31a20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 Methods for the
31a30 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 module */. void
31a40 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 *pClientData
31a50 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 /* Client
31a60 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 data for xCreat
31a70 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b e/xConnect */.);
31a80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31a90 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 : Register A Vir
31aa0 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 tual Table Imple
31ab0 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 31 mentation {H1821
31ac0 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 0} <S20400>.** E
31ad0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
31ae0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 * This routine i
31af0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74 s identical to t
31b00 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
31b10 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 74 te_module()] met
31b20 68 6f 64 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 hod,.** except t
31b30 68 61 74 20 69 74 20 68 61 73 20 61 6e 20 65 78 hat it has an ex
31b40 74 72 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f tra parameter to
31b50 20 73 70 65 63 69 66 79 20 0a 2a 2a 20 61 20 64 specify .** a d
31b60 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 estructor functi
31b70 6f 6e 20 66 6f 72 20 74 68 65 20 63 6c 69 65 6e on for the clien
31b80 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 t data pointer.
31b90 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 SQLite will.**
31ba0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
31bb0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 uctor function (
31bc0 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c if it is not NUL
31bd0 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a L) when SQLite.*
31be0 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 * no longer need
31bf0 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 s the pClientDat
31c00 61 20 70 6f 69 6e 74 65 72 2e 20 20 0a 2a 2f 0a a pointer. .*/.
31c10 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
31c20 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 E_EXPERIMENTAL i
31c30 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
31c40 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 e_module_v2(. s
31c50 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
31c60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c /* SQL
31c70 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ite connection t
31c80 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c o register modul
31c90 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 e with */. cons
31ca0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 t char *zName,
31cb0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
31cc0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a f the module */.
31cd0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f const sqlite3_
31ce0 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 module *p, /*
31cf0 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 Methods for the
31d00 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 module */. void
31d10 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 *pClientData,
31d20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 /* Client
31d30 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 data for xCreat
31d40 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 e/xConnect */.
31d50 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 void(*xDestroy)(
31d60 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f void*) /* Mo
31d70 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 dule destructor
31d80 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a function */.);..
31d90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31da0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e Virtual Table In
31db0 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 48 stance Object {H
31dc0 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18010} <S20400>.
31dd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
31de0 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58 50 ite3_vtab.** EXP
31df0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
31e00 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 Every [virtual t
31e10 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 able module] imp
31e20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 lementation uses
31e30 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f a subclass.** o
31e40 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
31e50 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 structure to des
31e60 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c cribe a particul
31e70 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f ar instance.** o
31e80 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 f the [virtual t
31e90 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 able]. Each sub
31ea0 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 class will.** be
31eb0 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 tailored to the
31ec0 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 specific needs
31ed0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d of the module im
31ee0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a plementation..**
31ef0 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 The purpose of
31f00 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 this superclass
31f10 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 is to define cer
31f20 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 tain fields that
31f30 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 are.** common t
31f40 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 o all module imp
31f50 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a lementations..**
31f60 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c .** Virtual tabl
31f70 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 es methods can s
31f80 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 et an error mess
31f90 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 age by assigning
31fa0 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 a.** string obt
31fb0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
31fc0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 te3_mprintf()] t
31fd0 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 o zErrMsg. The
31fe0 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a method should.**
31ff0 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 take care that
32000 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 any prior string
32010 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 is freed by a c
32020 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
32030 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 free()].** prior
32040 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 to assigning a
32050 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 new string to zE
32060 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 rrMsg. After th
32070 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a e error message.
32080 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 ** is delivered
32090 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 up to the client
320a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 application, th
320b0 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 e string will be
320c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
320d0 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 * freed by sqlit
320e0 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 e3_free() and th
320f0 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 e zErrMsg field
32100 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a will be zeroed..
32110 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
32120 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 3_vtab {. const
32130 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
32140 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 *pModule; /* Th
32150 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 e module for thi
32160 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 s virtual table
32170 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 */. int nRef;
32180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
32190 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 /* NO LONGE
321a0 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72 R USED */. char
321b0 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 *zErrMsg;
321c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 /* E
321d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f rror message fro
321e0 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 m sqlite3_mprint
321f0 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 f() */. /* Virt
32200 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d ual table implem
32210 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 entations will t
32220 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 ypically add add
32230 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a itional fields *
32240 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
32250 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 3REF: Virtual Ta
32260 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 ble Cursor Objec
32270 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32 30 t {H18020} <S20
32280 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 400>.** KEYWORDS
32290 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 : sqlite3_vtab_c
322a0 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 ursor {virtual t
322b0 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 20 able cursor}.**
322c0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
322d0 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 ** Every [virtua
322e0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 l table module]
322f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 implementation u
32300 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f ses a subclass o
32310 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 f the.** followi
32320 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 ng structure to
32330 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 describe cursors
32340 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f that point into
32350 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c the.** [virtual
32360 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 table] and are
32370 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 used.** to loop
32380 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 through the virt
32390 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 ual table. Curs
323a0 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20 ors are created
323b0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
323c0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 lite3_module.xOp
323d0 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 en | xOpen] meth
323e0 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 od of the module
323f0 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79 and are destroy
32400 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 ed.** by the [sq
32410 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c lite3_module.xCl
32420 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 ose | xClose] me
32430 74 68 6f 64 2e 20 20 43 75 73 73 6f 72 73 20 61 thod. Cussors a
32440 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 re used.** by th
32450 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e e [xFilter], [xN
32460 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 ext], [xEof], [x
32470 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 Column], and [xR
32480 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a owid] methods.**
32490 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 of the module.
324a0 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 Each module imp
324b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c lementation will
324c0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 define.** the c
324d0 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 ontent of a curs
324e0 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 or structure to
324f0 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 suit its own nee
32500 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 ds..**.** This s
32510 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 uperclass exists
32520 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 in order to def
32530 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 ine fields of th
32540 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a e cursor that.**
32550 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 are common to a
32560 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ll implementatio
32570 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 ns..*/.struct sq
32580 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
32590 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 r {. sqlite3_vt
325a0 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 ab *pVtab;
325b0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 /* Virtual table
325c0 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 of this cursor
325d0 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 */. /* Virtual
325e0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 table implementa
325f0 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 tions will typic
32600 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f ally add additio
32610 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b nal fields */.};
32620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
32630 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 : Declare The Sc
32640 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 hema Of A Virtua
32650 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30 7d l Table {H18280}
32660 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 <S20400>.** EXP
32670 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
32680 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e The [xCreate] an
32690 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 d [xConnect] met
326a0 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 hods of a.** [vi
326b0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 rtual table modu
326c0 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e le] call this in
326d0 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 terface.** to de
326e0 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 clare the format
326f0 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 (the names and
32700 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 datatypes of the
32710 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 columns) of.**
32720 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c the virtual tabl
32730 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e es they implemen
32740 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t..*/.SQLITE_API
32750 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 SQLITE_EXPERIME
32760 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
32770 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 _declare_vtab(sq
32780 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 lite3*, const ch
32790 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a ar *zSQL);../*.*
327a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 * CAPI3REF: Over
327b0 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 load A Function
327c0 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 For A Virtual Ta
327d0 62 6c 65 20 7b 48 31 38 33 30 30 7d 20 3c 53 32 ble {H18300} <S2
327e0 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 0400>.** EXPERIM
327f0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 56 69 72 74 ENTAL.**.** Virt
32800 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 ual tables can p
32810 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 rovide alternati
32820 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ve implementatio
32830 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ns of functions.
32840 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46 ** using the [xF
32850 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 indFunction] met
32860 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74 hod of the [virt
32870 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 ual table module
32880 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 ]. .** But glob
32890 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 al versions of t
328a0 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a hose functions.*
328b0 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 * must exist in
328c0 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 order to be over
328d0 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 loaded..**.** Th
328e0 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 is API makes sur
328f0 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 e a global versi
32900 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e on of a function
32910 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c with a particul
32920 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e ar.** name and n
32930 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 umber of paramet
32940 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 ers exists. If
32950 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e no such function
32960 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 exists.** befor
32970 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61 e this API is ca
32980 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 lled, a new func
32990 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e tion is created.
329a0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 The implementa
329b0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e tion.** of the n
329c0 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 ew function alwa
329d0 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 ys causes an exc
329e0 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 eption to be thr
329f0 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 own. So.** the
32a00 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 new function is
32a10 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 not good for any
32a20 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e thing by itself.
32a30 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 Its only.** pu
32a40 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 rpose is to be a
32a50 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e placeholder fun
32a60 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 ction that can b
32a70 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 e overloaded.**
32a80 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 by a [virtual ta
32a90 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ble]..*/.SQLITE_
32aa0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 API SQLITE_EXPER
32ab0 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 IMENTAL int sqli
32ac0 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e te3_overload_fun
32ad0 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 ction(sqlite3*,
32ae0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e const char *zFun
32af0 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 cName, int nArg)
32b00 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 ;../*.** The int
32b10 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 erface to the vi
32b20 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 rtual-table mech
32b30 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 anism defined ab
32b40 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 ove (back up.**
32b50 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d to a comment rem
32b60 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 arkably similar
32b70 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 to this one) is
32b80 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 currently consid
32b90 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 ered.** to be ex
32ba0 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 perimental. The
32bb0 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 interface might
32bc0 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d change in incom
32bd0 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a patible ways..**
32be0 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 If this is a pr
32bf0 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 oblem for you, d
32c00 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e o not use the in
32c10 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 terface at this
32c20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e time..**.** When
32c30 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 the virtual-tab
32c40 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 le mechanism sta
32c50 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c bilizes, we will
32c60 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 declare the.**
32c70 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c interface fixed,
32c80 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 support it inde
32c90 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 finitely, and re
32ca0 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e move this commen
32cb0 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 t..**.****** EXP
32cc0 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a ERIMENTAL - subj
32cd0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 ect to change wi
32ce0 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a thout notice ***
32cf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a ***********.*/..
32d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32d10 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f A Handle To An O
32d20 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 30 30 pen BLOB {H17800
32d30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 45 } <S30230>.** KE
32d40 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 YWORDS: {BLOB ha
32d50 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 ndle} {BLOB hand
32d60 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e les}.**.** An in
32d70 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
32d80 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
32d90 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e an open BLOB on
32da0 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 which.** [sqlit
32db0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 e3_blob_open | i
32dc0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 ncremental BLOB
32dd0 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 I/O] can be perf
32de0 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 ormed..** Object
32df0 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 s of this type a
32e00 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 re created by [s
32e10 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
32e20 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 ()].** and destr
32e30 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 oyed by [sqlite3
32e40 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a _blob_close()]..
32e50 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
32e60 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 blob_read()] and
32e70 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 [sqlite3_blob_w
32e80 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 rite()] interfac
32e90 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 es.** can be use
32ea0 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 d to read or wri
32eb0 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 te small subsect
32ec0 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 ions of the BLOB
32ed0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
32ee0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 3_blob_bytes()]
32ef0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
32f00 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
32f10 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e e BLOB in bytes.
32f20 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
32f30 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 ct sqlite3_blob
32f40 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f sqlite3_blob;../
32f50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
32f60 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 pen A BLOB For I
32f70 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b ncremental I/O {
32f80 48 31 37 38 31 30 7d 20 3c 53 33 30 32 33 30 3e H17810} <S30230>
32f90 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
32fa0 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b rfaces opens a [
32fb0 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 BLOB handle | ha
32fc0 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f ndle] to the BLO
32fd0 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 B located.** in
32fe0 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e row iRow, column
32ff0 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 zColumn, table
33000 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 zTable in databa
33010 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 se zDb;.** in ot
33020 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 her words, the s
33030 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f ame BLOB that wo
33040 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 uld be selected
33050 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a by:.**.** <pre>.
33060 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 ** SELECT zC
33070 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a olumn FROM zDb.z
33080 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 Table WHERE [row
33090 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c id] = iRow;.** <
330a0 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a /pre> {END}.**.*
330b0 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 * If the flags p
330c0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d arameter is non-
330d0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 zero, then the B
330e0 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f LOB is opened fo
330f0 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 r read.** and wr
33100 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 ite access. If i
33110 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 t is zero, the B
33120 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f LOB is opened fo
33130 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a r read access..*
33140 2a 20 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 * It is not poss
33150 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 ible to open a c
33160 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 olumn that is pa
33170 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f rt of an index o
33180 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 r primary .** ke
33190 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e y for writing. ^
331a0 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 If [foreign key
331b0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65 constraints] are
331c0 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20 enabled, it is
331d0 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 .** not possible
331e0 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d to open a colum
331f0 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f n that is part o
33200 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 f a [child key]
33210 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a for writing..**.
33220 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
33230 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 database name i
33240 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 s not the filena
33250 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 me that contains
33260 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
33270 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20 but rather the
33280 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 symbolic name of
33290 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 the database th
332a0 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 at.** is assigne
332b0 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 d when the datab
332c0 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 ase is connected
332d0 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e using [ATTACH].
332e0 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61 69 6e .** For the main
332f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
33300 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
33310 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 e is "main"..**
33320 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c For TEMP tables,
33330 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
33340 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a me is "temp"..**
33350 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 .** On success,
33360 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
33370 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 eturned and the
33380 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 new [BLOB handle
33390 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 ] is written.**
333a0 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 to *ppBlob. Othe
333b0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 rwise an [error
333c0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
333d0 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 d and *ppBlob is
333e0 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 set.** to be a
333f0 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a null pointer..**
33400 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 This function s
33410 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 ets the [databas
33420 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 e connection] er
33430 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 ror code and mes
33440 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 sage.** accessib
33450 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f le via [sqlite3_
33460 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b errcode()] and [
33470 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
33480 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a ] and related.**
33490 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 4e 6f 74 functions. Not
334a0 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c e that the *ppBl
334b0 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 ob variable is a
334c0 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 lways initialize
334d0 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 d in a.** way th
334e0 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65 at makes it safe
334f0 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 to invoke [sqli
33500 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 te3_blob_close()
33510 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 ] on *ppBlob.**
33520 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 regardless of th
33530 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 e success or fai
33540 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75 lure of this rou
33550 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 tine..**.** If t
33560 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c he row that a BL
33570 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 OB handle points
33580 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 to is modified
33590 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 by an.** [UPDATE
335a0 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 ], [DELETE], or
335b0 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d by [ON CONFLICT]
335c0 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a side-effects.**
335d0 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 then the BLOB h
335e0 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 andle is marked
335f0 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a as "expired"..**
33600 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 This is true if
33610 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 any column of t
33620 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 he row is change
33630 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e d, even a column
33640 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 .** other than t
33650 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 he one the BLOB
33660 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f handle is open o
33670 6e 2e 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b n..** Calls to [
33680 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 sqlite3_blob_rea
33690 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 d()] and [sqlite
336a0 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 3_blob_write()]
336b0 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 for.** a expired
336c0 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 BLOB handle fai
336d0 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e l with an return
336e0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 code of [SQLITE
336f0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e _ABORT]..** Chan
33700 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f ges written into
33710 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f a BLOB prior to
33720 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 the BLOB expiri
33730 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f ng are not.** ro
33740 6c 6c 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 llback by the ex
33750 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 piration of the
33760 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e BLOB. Such chan
33770 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 ges will eventua
33780 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 lly.** commit if
33790 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
337a0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f continues to co
337b0 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 mpletion..**.**
337c0 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 Use the [sqlite3
337d0 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 _blob_bytes()] i
337e0 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74 65 nterface to dete
337f0 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f rmine the size o
33800 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 f.** the opened
33810 62 6c 6f 62 2e 20 20 54 68 65 20 73 69 7a 65 20 blob. The size
33820 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f of a blob may no
33830 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 t be changed by
33840 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 this.** interfac
33850 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50 44 e. Use the [UPD
33860 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 ATE] SQL command
33870 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73 to change the s
33880 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 ize of a.** blob
33890 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ..**.** The [sql
338a0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
338b0 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ob()] and [sqlit
338c0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c e3_result_zerobl
338d0 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 ob()] interfaces
338e0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c .** and the buil
338f0 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 t-in [zeroblob]
33900 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e SQL function can
33910 20 62 65 20 75 73 65 64 2c 20 69 66 20 64 65 73 be used, if des
33920 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 ired,.** to crea
33930 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 te an empty, zer
33940 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e o-filled blob in
33950 20 77 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f which to read o
33960 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a r write using.**
33970 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e this interface.
33980 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 .**.** To avoid
33990 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c a resource leak,
339a0 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f every open [BLO
339b0 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 B handle] should
339c0 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 eventually.** b
339d0 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 61 20 e released by a
339e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
339f0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a _blob_close()]..
33a00 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
33a10 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 31 33 5d 20 ts:.** [H17813]
33a20 5b 48 31 37 38 31 34 5d 20 5b 48 31 37 38 31 36 [H17814] [H17816
33a30 5d 20 5b 48 31 37 38 31 39 5d 20 5b 48 31 37 38 ] [H17819] [H178
33a40 32 31 5d 20 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a 21] [H17824].*/.
33a50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
33a60 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
33a70 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 (. sqlite3*,.
33a80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c const char *zDb,
33a90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
33aa0 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 Table,. const c
33ab0 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 har *zColumn,.
33ac0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 sqlite3_int64 iR
33ad0 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c ow,. int flags,
33ae0 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 . sqlite3_blob
33af0 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a **ppBlob.);../*.
33b00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f ** CAPI3REF: Clo
33b10 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 se A BLOB Handle
33b20 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30 32 33 {H17830} <S3023
33b30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 20 0>.**.** Closes
33b40 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 an open [BLOB ha
33b50 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f ndle]..**.** Clo
33b60 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c sing a BLOB shal
33b70 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 l cause the curr
33b80 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 ent transaction
33b90 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 to commit.** if
33ba0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 there are no oth
33bb0 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e er BLOBs, no pen
33bc0 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 ding prepared st
33bd0 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 atements, and th
33be0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
33bf0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b nnection is in [
33c00 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d autocommit mode]
33c10 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72 69 74 ..** If any writ
33c20 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20 es were made to
33c30 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d the BLOB, they m
33c40 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20 ight be held in
33c50 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 cache.** until t
33c60 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 he close operati
33c70 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20 on if they will
33c80 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 fit..**.** Closi
33c90 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 ng the BLOB ofte
33ca0 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 n forces the cha
33cb0 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 nges.** out to d
33cc0 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e isk and so if an
33cd0 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 y I/O errors occ
33ce0 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 ur, they will li
33cf0 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 kely occur.** at
33d00 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 the time when t
33d10 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 he BLOB is close
33d20 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74 d. Any errors t
33d30 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 hat occur during
33d40 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 .** closing are
33d50 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f reported as a no
33d60 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 n-zero return va
33d70 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42 lue..**.** The B
33d80 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e LOB is closed un
33d90 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 conditionally.
33da0 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 Even if this rou
33db0 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 tine returns.**
33dc0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 an error code, t
33dd0 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c he BLOB is still
33de0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 43 closed..**.** C
33df0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 alling this rout
33e00 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 ine with a null
33e10 70 6f 69 6e 74 65 72 20 28 77 68 69 63 68 20 61 pointer (which a
33e20 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 s would be retur
33e30 6e 65 64 0a 2a 2a 20 62 79 20 66 61 69 6c 65 64 ned.** by failed
33e40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
33e50 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 3_blob_open()])
33e60 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f is a harmless no
33e70 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 -op..**.** Requi
33e80 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 rements:.** [H17
33e90 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b 48 833] [H17836] [H
33ea0 31 37 38 33 39 5d 0a 2a 2f 0a 53 51 4c 49 54 45 17839].*/.SQLITE
33eb0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
33ec0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 _blob_close(sqli
33ed0 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a te3_blob *);../*
33ee0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
33ef0 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 turn The Size Of
33f00 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 An Open BLOB {H
33f10 31 37 38 34 30 7d 20 3c 53 33 30 32 33 30 3e 0a 17840} <S30230>.
33f20 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 **.** Returns th
33f30 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 e size in bytes
33f40 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 of the BLOB acce
33f50 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a ssible via the .
33f60 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 ** successfully
33f70 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e opened [BLOB han
33f80 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 dle] in its only
33f90 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 0a argument. The.
33fa0 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 ** incremental b
33fb0 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 lob I/O routines
33fc0 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f can only read o
33fd0 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78 r overwriting ex
33fe0 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 isting.** blob c
33ff0 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e ontent; they can
34000 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 73 not change the s
34010 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a ize of a blob..*
34020 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
34030 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 e only works on
34040 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 a [BLOB handle]
34050 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 which has been c
34060 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 reated.** by a p
34070 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 rior successful
34080 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
34090 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e _blob_open()] an
340a0 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a d which has not.
340b0 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 ** been closed b
340c0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f y [sqlite3_blob_
340d0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 close()]. Passi
340e0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 ng any other poi
340f0 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 nter in.** to th
34100 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c is routine resul
34110 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 ts in undefined
34120 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 and probably und
34130 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f esirable behavio
34140 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 r..**.** Require
34150 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 34 ments:.** [H1784
34160 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 3].*/.SQLITE_API
34170 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f int sqlite3_blo
34180 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f b_bytes(sqlite3_
34190 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 blob *);../*.**
341a0 43 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 CAPI3REF: Read D
341b0 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 ata From A BLOB
341c0 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 Incrementally {H
341d0 31 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a 17850} <S30230>.
341e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
341f0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 ion is used to r
34200 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e ead data from an
34210 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 open [BLOB hand
34220 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 le] into a.** ca
34230 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 ller-supplied bu
34240 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 ffer. N bytes of
34250 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 data are copied
34260 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a into buffer Z.*
34270 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 * from the open
34280 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 BLOB, starting a
34290 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 t offset iOffset
342a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 ..**.** If offse
342b0 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 t iOffset is les
342c0 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 s than N bytes f
342d0 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 rom the end of t
342e0 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c he BLOB,.** [SQL
342f0 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 ITE_ERROR] is re
34300 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 turned and no da
34310 74 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 ta is read. If
34320 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a N or iOffset is.
34330 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 ** less than zer
34340 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 o, [SQLITE_ERROR
34350 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
34360 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 d no data is rea
34370 64 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f d..** The size o
34380 66 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 f the blob (and
34390 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 hence the maximu
343a0 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 m value of N+iOf
343b0 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 fset).** can be
343c0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 determined using
343d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c the [sqlite3_bl
343e0 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 ob_bytes()] inte
343f0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 rface..**.** An
34400 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 attempt to read
34410 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 from an expired
34420 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 [BLOB handle] fa
34430 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 ils with an.** e
34440 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 rror code of [SQ
34450 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a LITE_ABORT]..**.
34460 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 ** On success, S
34470 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
34480 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 rned..** Otherwi
34490 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f se, an [error co
344a0 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e de] or an [exten
344b0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 ded error code]
344c0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
344d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
344e0 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 only works on a
344f0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 [BLOB handle] wh
34500 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 ich has been cre
34510 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 ated.** by a pri
34520 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 or successful ca
34530 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ll to [sqlite3_b
34540 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 lob_open()] and
34550 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a which has not.**
34560 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 been closed by
34570 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c [sqlite3_blob_cl
34580 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 ose()]. Passing
34590 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 any other point
345a0 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 er in.** to this
345b0 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 routine results
345c0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e in undefined an
345d0 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 d probably undes
345e0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e irable behavior.
345f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
34600 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 [sqlite3_blob_w
34610 72 69 74 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 rite()]..**.** R
34620 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
34630 5b 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36 [H17853] [H17856
34640 5d 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38 ] [H17859] [H178
34650 36 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31 62] [H17863] [H1
34660 37 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 7865] [H17868].*
34670 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
34680 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 sqlite3_blob_re
34690 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 ad(sqlite3_blob
346a0 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 *, void *Z, int
346b0 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b N, int iOffset);
346c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
346d0 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 : Write Data Int
346e0 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 o A BLOB Increme
346f0 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d 20 ntally {H17870}
34700 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S30230>.**.** T
34710 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
34720 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 used to write da
34730 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 ta into an open
34740 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 [BLOB handle] fr
34750 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 om a.** caller-s
34760 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 upplied buffer.
34770 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 N bytes of data
34780 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 are copied from
34790 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 the buffer Z.**
347a0 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c into the open BL
347b0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 OB, starting at
347c0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a offset iOffset..
347d0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 4c **.** If the [BL
347e0 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 OB handle] passe
347f0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
34800 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 rgument was not
34810 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 opened for.** wr
34820 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 iting (the flags
34830 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
34840 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
34850 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a ()] was zero),.*
34860 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * this function
34870 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
34880 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a READONLY]..**.**
34890 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d This function m
348a0 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 ay only modify t
348b0 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 he contents of t
348c0 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a he BLOB; it is.*
348d0 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 * not possible t
348e0 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 o increase the s
348f0 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 ize of a BLOB us
34900 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a ing this API..**
34910 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 If offset iOffs
34920 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 et is less than
34930 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 N bytes from the
34940 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 end of the BLOB
34950 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 ,.** [SQLITE_ERR
34960 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 OR] is returned
34970 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 and no data is w
34980 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 73 ritten. If N is
34990 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 .** less than ze
349a0 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ro [SQLITE_ERROR
349b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
349c0 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 d no data is wri
349d0 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a tten..** The siz
349e0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61 e of the BLOB (a
349f0 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 nd hence the max
34a00 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b imum value of N+
34a10 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 iOffset).** can
34a20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 be determined us
34a30 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ing the [sqlite3
34a40 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 _blob_bytes()] i
34a50 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
34a60 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72 An attempt to wr
34a70 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65 ite to an expire
34a80 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 d [BLOB handle]
34a90 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a fails with an.**
34aa0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b error code of [
34ab0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 SQLITE_ABORT].
34ac0 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c Writes to the BL
34ad0 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 OB that occurred
34ae0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b .** before the [
34af0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 BLOB handle] exp
34b00 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c ired are not rol
34b10 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a led back by the.
34b20 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 ** expiration of
34b30 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f the handle, tho
34b40 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 ugh of course th
34b50 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 ose changes migh
34b60 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f t.** have been o
34b70 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 verwritten by th
34b80 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 e statement that
34b90 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f expired the BLO
34ba0 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 B handle.** or b
34bb0 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 y other independ
34bc0 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a ent statements..
34bd0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
34be0 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 , SQLITE_OK is r
34bf0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 eturned..** Othe
34c00 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f rwise, an [erro
34c10 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 r code] or an [e
34c20 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
34c30 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
34c40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
34c50 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f ine only works o
34c60 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 n a [BLOB handle
34c70 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e ] which has been
34c80 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 created.** by a
34c90 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
34ca0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
34cb0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 e3_blob_open()]
34cc0 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f and which has no
34cd0 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 t.** been closed
34ce0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f by [sqlite3_blo
34cf0 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 b_close()]. Pas
34d00 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 sing any other p
34d10 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 ointer in.** to
34d20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 this routine res
34d30 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 ults in undefine
34d40 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 d and probably u
34d50 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 ndesirable behav
34d60 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ior..**.** See a
34d70 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c lso: [sqlite3_bl
34d80 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a 2a ob_read()]..**.*
34d90 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
34da0 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 37 ** [H17873] [H17
34db0 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 48 874] [H17875] [H
34dc0 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d 20 17876] [H17877]
34dd0 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38 32 [H17879] [H17882
34de0 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 48 ] [H17885].** [H
34df0 31 37 38 38 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 17888].*/.SQLITE
34e00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
34e10 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 _blob_write(sqli
34e20 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 te3_blob *, cons
34e30 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e t void *z, int n
34e40 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a , int iOffset);.
34e50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
34e60 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79 Virtual File Sy
34e70 73 74 65 6d 20 4f 62 6a 65 63 74 73 20 7b 48 31 stem Objects {H1
34e80 31 32 30 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 1200} <S20100>.*
34e90 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 *.** A virtual f
34ea0 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 ilesystem (VFS)
34eb0 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 is an [sqlite3_v
34ec0 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 fs] object.** th
34ed0 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 at SQLite uses t
34ee0 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 o interact.** wi
34ef0 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e th the underlyin
34f00 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 g operating syst
34f10 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 em. Most SQLite
34f20 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 builds come wit
34f30 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 h a.** single de
34f40 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 fault VFS that i
34f50 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f s appropriate fo
34f60 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 r the host compu
34f70 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 ter..** New VFSe
34f80 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 s can be registe
34f90 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 red and existing
34fa0 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e VFSes can be un
34fb0 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 registered..** T
34fc0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 he following int
34fd0 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 erfaces are prov
34fe0 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ided..**.** The
34ff0 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 sqlite3_vfs_find
35000 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
35010 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
35020 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 o a VFS given it
35030 73 20 6e 61 6d 65 2e 0a 2a 2a 20 4e 61 6d 65 73 s name..** Names
35040 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74 are case sensit
35050 69 76 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 ive..** Names ar
35060 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 e zero-terminate
35070 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e d UTF-8 strings.
35080 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 .** If there is
35090 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c no match, a NULL
350a0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 pointer is retu
350b0 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 7a 56 66 73 rned..** If zVfs
350c0 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 Name is NULL the
350d0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 n the default VF
350e0 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a S is returned..*
350f0 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 61 *.** New VFSes a
35100 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 re registered wi
35110 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 th sqlite3_vfs_r
35120 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 45 61 egister()..** Ea
35130 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d ch new VFS becom
35140 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 es the default V
35150 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 FS if the makeDf
35160 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a lt flag is set..
35170 2a 2a 20 54 68 65 20 73 61 6d 65 20 56 46 53 20 ** The same VFS
35180 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 can be registere
35190 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 d multiple times
351a0 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e without injury.
351b0 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 .** To make an e
351c0 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f xisting VFS into
351d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 the default VFS
351e0 2c 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67 , register it ag
351f0 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ain.** with the
35200 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 makeDflt flag se
35210 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 t. If two diffe
35220 72 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 rent VFSes with
35230 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 the.** same name
35240 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 2c are registered,
35250 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
35260 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20 undefined. If
35270 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 a.** VFS is regi
35280 73 74 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 stered with a na
35290 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 me that is NULL
352a0 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 or an empty stri
352b0 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ng,.** then the
352c0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
352d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 fined..**.** Unr
352e0 65 67 69 73 74 65 72 20 61 20 56 46 53 20 77 69 egister a VFS wi
352f0 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 th the sqlite3_v
35300 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 fs_unregister()
35310 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 66 interface..** If
35320 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 the default VFS
35330 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 is unregistered
35340 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 , another VFS is
35350 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 chosen as.** th
35360 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 e default. The
35370 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e choice for the n
35380 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 ew VFS is arbitr
35390 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ary..**.** Requi
353a0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 rements:.** [H11
353b0 32 30 33 5d 20 5b 48 31 31 32 30 36 5d 20 5b 48 203] [H11206] [H
353c0 31 31 32 30 39 5d 20 5b 48 31 31 32 31 32 5d 20 11209] [H11212]
353d0 5b 48 31 31 32 31 35 5d 20 5b 48 31 31 32 31 38 [H11215] [H11218
353e0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
353f0 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c sqlite3_vfs *sql
35400 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f ite3_vfs_find(co
35410 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 nst char *zVfsNa
35420 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 me);.SQLITE_API
35430 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f int sqlite3_vfs_
35440 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 register(sqlite3
35450 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 _vfs*, int makeD
35460 66 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 flt);.SQLITE_API
35470 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 int sqlite3_vfs
35480 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 _unregister(sqli
35490 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a te3_vfs*);../*.*
354a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 * CAPI3REF: Mute
354b0 78 65 73 20 7b 48 31 37 30 30 30 7d 20 3c 53 32 xes {H17000} <S2
354c0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0000>.**.** The
354d0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 SQLite core uses
354e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
354f0 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 for thread.** sy
35500 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 nchronization. T
35510 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69 hough they are i
35520 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 ntended for inte
35530 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 rnal.** use by S
35540 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 QLite, code that
35550 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 links against S
35560 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d QLite is.** perm
35570 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 itted to use any
35580 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
35590 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 es..**.** The SQ
355a0 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 Lite source code
355b0 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 contains multip
355c0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
355d0 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d ns.** of these m
355e0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 utex routines.
355f0 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 An appropriate i
35600 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
35610 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 is selected aut
35620 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f omatically at co
35630 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65 mpile-time. The
35640 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d following.** im
35650 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 plementations ar
35660 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 e available in t
35670 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a he SQLite core:.
35680 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
35690 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 i> SQLITE_MUTE
356a0 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 X_OS2.** <li>
356b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 SQLITE_MUTEX_PTH
356c0 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 READ.** <li> S
356d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a QLITE_MUTEX_W32.
356e0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 ** <li> SQLITE
356f0 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c _MUTEX_NOOP.** <
35700 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 /ul>.**.** The S
35710 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 QLITE_MUTEX_NOOP
35720 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35730 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74 is a set of rout
35740 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 ines.** that doe
35750 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e s no real lockin
35760 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72 g and is appropr
35770 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e 0a iate for use in.
35780 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 ** a single-thre
35790 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e aded application
357a0 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 . The SQLITE_MU
357b0 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 TEX_OS2,.** SQLI
357c0 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 TE_MUTEX_PTHREAD
357d0 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 , and SQLITE_MUT
357e0 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 EX_W32 implement
357f0 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 ations.** are ap
35800 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 propriate for us
35810 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c e on OS/2, Unix,
35820 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a and Windows..**
35830 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 69 73 .** If SQLite is
35840 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
35850 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f he SQLITE_MUTEX_
35860 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73 APPDEF preproces
35870 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 sor.** macro def
35880 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51 ined (with "-DSQ
35890 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 LITE_MUTEX_APPDE
358a0 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d F=1"), then no m
358b0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e utex.** implemen
358c0 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 tation is includ
358d0 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 ed with the libr
358e0 61 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61 73 ary. In this cas
358f0 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 e the.** applica
35900 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 tion must supply
35910 20 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 a custom mutex
35920 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 implementation u
35930 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c sing the.** [SQL
35940 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
35950 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 ] option of the
35960 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
35970 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 function.** bef
35980 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 ore calling sqli
35990 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
359a0 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70 75 or any other pu
359b0 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a blic sqlite3_.**
359c0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 function that c
359d0 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 alls sqlite3_ini
359e0 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a tialize()..**.**
359f0 20 7b 48 31 37 30 31 31 7d 20 54 68 65 20 73 71 {H17011} The sq
35a00 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
35a10 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f c() routine allo
35a20 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d cates a new.** m
35a30 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 utex and returns
35a40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 a pointer to it
35a50 2e 20 7b 48 31 37 30 31 32 7d 20 49 66 20 69 74 . {H17012} If it
35a60 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a returns NULL.**
35a70 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 that means that
35a80 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e a mutex could n
35a90 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e ot be allocated.
35aa0 20 7b 48 31 37 30 31 33 7d 20 53 51 4c 69 74 65 {H17013} SQLite
35ab0 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 .** will unwind
35ac0 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 its stack and re
35ad0 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b turn an error. {
35ae0 48 31 37 30 31 34 7d 20 54 68 65 20 61 72 67 75 H17014} The argu
35af0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 ment.** to sqlit
35b00 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
35b10 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 is one of these
35b20 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
35b30 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ts:.**.** <ul>.*
35b40 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
35b50 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 UTEX_FAST.** <li
35b60 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
35b70 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 RECURSIVE.** <li
35b80 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
35b90 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a STATIC_MASTER.**
35ba0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
35bb0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a TEX_STATIC_MEM.*
35bc0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
35bd0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 UTEX_STATIC_MEM2
35be0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
35bf0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 _MUTEX_STATIC_PR
35c00 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 NG.** <li> SQLI
35c10 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
35c20 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c LRU.** <li> SQL
35c30 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
35c40 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a _LRU2.** </ul>.*
35c50 2a 0a 2a 2a 20 7b 48 31 37 30 31 35 7d 20 54 68 *.** {H17015} Th
35c60 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 e first two cons
35c70 74 61 6e 74 73 20 63 61 75 73 65 20 73 71 6c 69 tants cause sqli
35c80 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
35c90 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 ) to create.** a
35ca0 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54 68 65 new mutex. The
35cb0 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72 65 new mutex is re
35cc0 63 75 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c cursive when SQL
35cd0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
35ce0 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 IVE.** is used b
35cf0 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 ut not necessari
35d00 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 ly so when SQLIT
35d10 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20 E_MUTEX_FAST is
35d20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 used. {END}.** T
35d30 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 he mutex impleme
35d40 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ntation does not
35d50 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 need to make a
35d60 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 distinction.** b
35d70 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 etween SQLITE_MU
35d80 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e TEX_RECURSIVE an
35d90 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 d SQLITE_MUTEX_F
35da0 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a AST if it does.*
35db0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 * not want to.
35dc0 7b 48 31 37 30 31 36 7d 20 42 75 74 20 53 51 4c {H17016} But SQL
35dd0 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 ite will only re
35de0 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69 76 quest a recursiv
35df0 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 e mutex in.** ca
35e00 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65 61 ses where it rea
35e10 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 lly needs one.
35e20 7b 45 4e 44 7d 20 49 66 20 61 20 66 61 73 74 65 {END} If a faste
35e30 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 r non-recursive
35e40 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 mutex.** impleme
35e50 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c ntation is avail
35e60 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 able on the host
35e70 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d platform, the m
35e80 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a utex subsystem.*
35e90 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 * might return s
35ea0 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 uch a mutex in r
35eb0 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 esponse to SQLIT
35ec0 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a E_MUTEX_FAST..**
35ed0 0a 2a 2a 20 7b 48 31 37 30 31 37 7d 20 54 68 65 .** {H17017} The
35ee0 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 other allowed p
35ef0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c arameters to sql
35f00 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
35f10 28 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a () each return.*
35f20 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
35f30 20 73 74 61 74 69 63 20 70 72 65 65 78 69 73 74 static preexist
35f40 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d ing mutex. {END}
35f50 20 20 53 69 78 20 73 74 61 74 69 63 20 6d 75 74 Six static mut
35f60 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 exes are.** used
35f70 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 by the current
35f80 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 version of SQLit
35f90 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 e. Future versi
35fa0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a ons of SQLite.**
35fb0 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f may add additio
35fc0 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 nal static mutex
35fd0 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 es. Static mute
35fe0 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 xes are for inte
35ff0 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 rnal.** use by S
36000 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 QLite only. App
36010 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 lications that u
36020 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 se SQLite mutexe
36030 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 s should.** use
36040 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 only the dynamic
36050 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 mutexes returne
36060 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 d by SQLITE_MUTE
36070 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c X_FAST or.** SQL
36080 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
36090 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 IVE..**.** {H170
360a0 31 38 7d 20 4e 6f 74 65 20 74 68 61 74 20 69 66 18} Note that if
360b0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61 one of the dyna
360c0 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65 mic mutex parame
360d0 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 ters (SQLITE_MUT
360e0 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 EX_FAST.** or SQ
360f0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
36100 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68 SIVE) is used th
36110 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 en sqlite3_mutex
36120 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 _alloc().** retu
36130 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20 rns a different
36140 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63 mutex on every c
36150 61 6c 6c 2e 20 20 7b 48 31 37 30 33 34 7d 20 42 all. {H17034} B
36160 75 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 ut for the stati
36170 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 c.** mutex types
36180 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 , the same mutex
36190 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 is returned on
361a0 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 every call that
361b0 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 has.** the same
361c0 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a type number..**.
361d0 2a 2a 20 7b 48 31 37 30 31 39 7d 20 54 68 65 20 ** {H17019} The
361e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 sqlite3_mutex_fr
361f0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 ee() routine dea
36200 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 llocates a previ
36210 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ously.** allocat
36220 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 ed dynamic mutex
36230 2e 20 7b 48 31 37 30 32 30 7d 20 53 51 4c 69 74 . {H17020} SQLit
36240 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 e is careful to
36250 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 deallocate every
36260 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 .** dynamic mute
36270 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 x that it alloca
36280 74 65 73 2e 20 7b 41 31 37 30 32 31 7d 20 54 68 tes. {A17021} Th
36290 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 e dynamic mutexe
362a0 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e s must not be in
362b0 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65 .** use when the
362c0 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 y are deallocate
362d0 64 2e 20 7b 41 31 37 30 32 32 7d 20 41 74 74 65 d. {A17022} Atte
362e0 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f mpting to deallo
362f0 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a cate a static.**
36300 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 mutex results i
36310 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
36320 76 69 6f 72 2e 20 7b 48 31 37 30 32 33 7d 20 53 vior. {H17023} S
36330 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c QLite never deal
36340 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 locates.** a sta
36350 74 69 63 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d tic mutex. {END}
36360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
36370 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 e3_mutex_enter()
36380 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 and sqlite3_mut
36390 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65 ex_try() routine
363a0 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 s attempt.** to
363b0 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 7b enter a mutex. {
363c0 48 31 37 30 32 34 7d 20 49 66 20 61 6e 6f 74 68 H17024} If anoth
363d0 65 72 20 74 68 72 65 61 64 20 69 73 20 61 6c 72 er thread is alr
363e0 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 65 20 eady within the
363f0 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 mutex,.** sqlite
36400 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 3_mutex_enter()
36410 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 will block and s
36420 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
36430 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a () will return.*
36440 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 7b * SQLITE_BUSY. {
36450 48 31 37 30 32 35 7d 20 20 54 68 65 20 73 71 6c H17025} The sql
36460 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
36470 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
36480 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a ns [SQLITE_OK].*
36490 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 * upon successfu
364a0 6c 20 65 6e 74 72 79 2e 20 20 7b 48 31 37 30 32 l entry. {H1702
364b0 36 7d 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 6} Mutexes creat
364c0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 ed using.** SQLI
364d0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
364e0 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 VE can be entere
364f0 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 d multiple times
36500 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 by the same thr
36510 65 61 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 37 7d ead..** {H17027}
36520 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 In such cases t
36530 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 he,.** mutex mus
36540 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 t be exited an e
36550 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 qual number of t
36560 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 imes before anot
36570 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 her thread.** ca
36580 6e 20 65 6e 74 65 72 2e 20 20 7b 41 31 37 30 32 n enter. {A1702
36590 38 7d 20 49 66 20 74 68 65 20 73 61 6d 65 20 74 8} If the same t
365a0 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 hread tries to e
365b0 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a nter any other.*
365c0 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 * kind of mutex
365d0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 more than once,
365e0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
365f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 7b 48 undefined..** {H
36600 31 37 30 32 39 7d 20 53 51 4c 69 74 65 20 77 69 17029} SQLite wi
36610 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74 ll never exhibit
36620 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f .** such behavio
36630 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 r in its own use
36640 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a of mutexes..**.
36650 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 ** Some systems
36660 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 (for example, Wi
36670 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 ndows 95) do not
36680 20 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65 support the ope
36690 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d ration.** implem
366a0 65 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 ented by sqlite3
366b0 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f _mutex_try(). O
366c0 6e 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c n those systems,
366d0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
366e0 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 ry().** will alw
366f0 61 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 ays return SQLIT
36700 45 5f 42 55 53 59 2e 20 20 7b 48 31 37 30 33 30 E_BUSY. {H17030
36710 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 } The SQLite cor
36720 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 e only ever uses
36730 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 .** sqlite3_mute
36740 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 x_try() as an op
36750 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 timization so th
36760 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 is is acceptable
36770 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a behavior..**.**
36780 20 7b 48 31 37 30 33 31 7d 20 54 68 65 20 73 71 {H17031} The sq
36790 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
367a0 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74 e() routine exit
367b0 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77 s a mutex that w
367c0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 as.** previously
367d0 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20 entered by the
367e0 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 7b 41 same thread. {A
367f0 31 37 30 33 32 7d 20 54 68 65 20 62 65 68 61 76 17032} The behav
36800 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 ior.** is undefi
36810 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 ned if the mutex
36820 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
36830 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 y entered by the
36840 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 .** calling thre
36850 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 ad or is not cur
36860 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 rently allocated
36870 2e 20 20 7b 48 31 37 30 33 33 7d 20 53 51 4c 69 . {H17033} SQLi
36880 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 te will.** never
36890 20 64 6f 20 65 69 74 68 65 72 2e 20 7b 45 4e 44 do either. {END
368a0 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 }.**.** If the a
368b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
368c0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 e3_mutex_enter()
368d0 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f , sqlite3_mutex_
368e0 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c try(), or.** sql
368f0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
36900 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
36910 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 nter, then all t
36920 68 72 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hree routines.**
36930 20 62 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 behave as no-op
36940 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 s..**.** See als
36950 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 o: [sqlite3_mute
36960 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 x_held()] and [s
36970 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
36980 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 held()]..*/.SQLI
36990 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 6d TE_API sqlite3_m
369a0 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 utex *sqlite3_mu
369b0 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a tex_alloc(int);.
369c0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
369d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 sqlite3_mutex_fr
369e0 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ee(sqlite3_mutex
369f0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 *);.SQLITE_API v
36a00 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 oid sqlite3_mute
36a10 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f x_enter(sqlite3_
36a20 6d 75 74 65 78 2a 29 3b 0a 53 51 4c 49 54 45 5f mutex*);.SQLITE_
36a30 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
36a40 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 mutex_try(sqlite
36a50 33 5f 6d 75 74 65 78 2a 29 3b 0a 53 51 4c 49 54 3_mutex*);.SQLIT
36a60 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
36a70 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 e3_mutex_leave(s
36a80 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a qlite3_mutex*);.
36a90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
36aa0 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f Mutex Methods O
36ab0 62 6a 65 63 74 20 7b 48 31 37 31 32 30 7d 20 3c bject {H17120} <
36ac0 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52 S20130>.** EXPER
36ad0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e IMENTAL.**.** An
36ae0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
36af0 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 s structure defi
36b00 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 nes the low-leve
36b10 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 l routines.** us
36b20 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 ed to allocate a
36b30 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a nd use mutexes..
36b40 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 **.** Usually, t
36b50 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 he default mutex
36b60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
36b70 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c provided by SQL
36b80 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 ite are.** suffi
36b90 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 cient, however t
36ba0 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 he user has the
36bb0 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 option of substi
36bc0 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a tuting a custom.
36bd0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
36be0 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 n for specialize
36bf0 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 d deployments or
36c00 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 systems for whi
36c10 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 ch SQLite.** doe
36c20 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 s not provide a
36c30 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 suitable impleme
36c40 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 ntation. In this
36c50 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a case, the user.
36c60 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 ** creates and p
36c70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 opulates an inst
36c80 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 ance of this str
36c90 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a ucture to pass.*
36ca0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e * to sqlite3_con
36cb0 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 fig() along with
36cc0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
36cd0 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f FIG_MUTEX] optio
36ce0 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c n..** Additional
36cf0 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 ly, an instance
36d00 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
36d10 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 e can be used as
36d20 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 an.** output va
36d30 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 riable when quer
36d40 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 ying the system
36d50 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 for the current
36d60 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 mutex.** impleme
36d70 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 ntation, using t
36d80 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
36d90 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 G_GETMUTEX] opti
36da0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d on..**.** The xM
36db0 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 utexInit method
36dc0 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 defined by this
36dd0 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 structure is inv
36de0 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 oked as.** part
36df0 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 of system initia
36e00 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 lization by the
36e10 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
36e20 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a ze() function..*
36e30 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 65 20 78 * {H17001} The x
36e40 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e MutexInit routin
36e50 65 20 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65 e shall be calle
36e60 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 65 d by SQLite once
36e70 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 for each.** eff
36e80 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b ective call to [
36e90 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
36ea0 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ze()]..**.** The
36eb0 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f xMutexEnd metho
36ec0 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 d defined by thi
36ed0 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 s structure is i
36ee0 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 nvoked as.** par
36ef0 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74 t of system shut
36f00 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69 down by the sqli
36f10 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 te3_shutdown() f
36f20 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 unction. The.**
36f30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
36f40 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 f this method is
36f50 20 65 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c expected to rel
36f60 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e ease all outstan
36f70 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 ding.** resource
36f80 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 s obtained by th
36f90 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 e mutex methods
36fa0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 implementation,
36fb0 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 especially.** th
36fc0 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 ose obtained by
36fd0 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d the xMutexInit m
36fe0 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20 ethod. {H17003}
36ff0 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a The xMutexEnd().
37000 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 ** interface sha
37010 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e ll be invoked on
37020 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c ce for each call
37030 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 to [sqlite3_shu
37040 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 tdown()]..**.**
37050 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 The remaining se
37060 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 ven methods defi
37070 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 ned by this stru
37080 63 74 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c cture (xMutexAll
37090 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 oc,.** xMutexFre
370a0 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 e, xMutexEnter,
370b0 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 xMutexTry, xMute
370c0 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 xLeave, xMutexHe
370d0 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 ld and.** xMutex
370e0 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 Notheld) impleme
370f0 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 nt the following
37100 20 69 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 interfaces (res
37110 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a pectively):.**.*
37120 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e * <ul>.** <li>
37130 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 [sqlite3_mutex
37140 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a _alloc()] </li>.
37150 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
37160 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 te3_mutex_free()
37170 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
37180 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
37190 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e x_enter()] </li>
371a0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
371b0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
371c0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
371d0 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
371e0 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e x_leave()] </li>
371f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
37200 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
37210 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
37220 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
37230 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f ex_notheld()] </
37240 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a li>.** </ul>.**.
37250 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 ** The only diff
37260 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 erence is that t
37270 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 he public sqlite
37280 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 3_XXX functions
37290 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 enumerated.** ab
372a0 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e ove silently ign
372b0 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 ore any invocati
372c0 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 20 ons that pass a
372d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 NULL pointer ins
372e0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c tead.** of a val
372f0 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e id mutex handle.
37300 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
37310 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 ions of the meth
37320 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 ods defined.** b
37330 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 y this structure
37340 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 are not require
37350 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 d to handle this
37360 20 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c case, the resul
37370 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 ts.** of passing
37380 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
37390 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c instead of a val
373a0 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 id mutex handle
373b0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a are undefined.**
373c0 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 (i.e. it is acc
373d0 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 eptable to provi
373e0 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 de an implementa
373f0 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 tion that segfau
37400 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 lts if.** it is
37410 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f passed a NULL po
37420 69 6e 74 65 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 inter)..**.** Th
37430 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d e xMutexInit() m
37440 65 74 68 6f 64 20 6d 75 73 74 20 62 65 20 74 68 ethod must be th
37450 72 65 61 64 73 61 66 65 2e 20 20 49 74 20 6d 75 readsafe. It mu
37460 73 74 20 62 65 20 68 61 72 6d 6c 65 73 73 20 74 st be harmless t
37470 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 78 4d 75 74 o.** invoke xMut
37480 65 78 49 6e 69 74 28 29 20 6d 75 74 69 70 6c 65 exInit() mutiple
37490 20 74 69 6d 65 73 20 77 69 74 68 69 6e 20 74 68 times within th
374a0 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 20 61 e same process a
374b0 6e 64 20 77 69 74 68 6f 75 74 0a 2a 2a 20 69 6e nd without.** in
374c0 74 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c 73 20 tervening calls
374d0 74 6f 20 78 4d 75 74 65 78 45 6e 64 28 29 2e 20 to xMutexEnd().
374e0 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 Second and subs
374f0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a equent calls to.
37500 2a 2a 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 ** xMutexInit()
37510 6d 75 73 74 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a must be no-ops..
37520 2a 2a 0a 2a 2a 20 78 4d 75 74 65 78 49 6e 69 74 **.** xMutexInit
37530 28 29 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 () must not use
37540 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c SQLite memory al
37550 6c 6f 63 61 74 69 6f 6e 20 28 5b 73 71 6c 69 74 location ([sqlit
37560 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 e3_malloc()].**
37570 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61 74 and its associat
37580 65 73 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c es). Similarly,
37590 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d xMutexAlloc() m
375a0 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 ust not use SQLi
375b0 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c te memory.** all
375c0 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 ocation for a st
375d0 61 74 69 63 20 6d 75 74 65 78 2e 20 20 48 6f 77 atic mutex. How
375e0 65 76 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 ever xMutexAlloc
375f0 28 29 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74 () may use SQLit
37600 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f e.** memory allo
37610 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 cation for a fas
37620 74 20 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d t or recursive m
37630 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 utex..**.** SQLi
37640 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
37650 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d he xMutexEnd() m
37660 65 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 ethod when [sqli
37670 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
37680 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 is.** called, bu
37690 74 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 t only if the pr
376a0 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 ior call to xMut
376b0 65 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 exInit returned
376c0 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 SQLITE_OK..** If
376d0 20 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c xMutexInit fail
376e0 73 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 s in any way, it
376f0 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 is expected to
37700 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 clean up after i
37710 74 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 tself.** prior t
37720 6f 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a o returning..*/.
37730 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
37740 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
37750 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 hods sqlite3_mut
37760 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 ex_methods;.stru
37770 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
37780 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 _methods {. int
37790 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 (*xMutexInit)(v
377a0 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d oid);. int (*xM
377b0 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a utexEnd)(void);.
377c0 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 sqlite3_mutex
377d0 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 *(*xMutexAlloc)(
377e0 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 int);. void (*x
377f0 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 MutexFree)(sqlit
37800 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 e3_mutex *);. v
37810 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 oid (*xMutexEnte
37820 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 r)(sqlite3_mutex
37830 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 *);. int (*xMu
37840 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f texTry)(sqlite3_
37850 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 mutex *);. void
37860 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 (*xMutexLeave)(
37870 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 sqlite3_mutex *)
37880 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 ;. int (*xMutex
37890 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 Held)(sqlite3_mu
378a0 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a tex *);. int (*
378b0 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 xMutexNotheld)(s
378c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b qlite3_mutex *);
378d0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
378e0 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 REF: Mutex Verif
378f0 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 ication Routines
37900 20 7b 48 31 37 30 38 30 7d 20 3c 53 32 30 31 33 {H17080} <S2013
37910 30 3e 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 0> <S30800>.**.*
37920 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 * The sqlite3_mu
37930 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 tex_held() and s
37940 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
37950 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a held() routines.
37960 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 ** are intended
37970 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 for use inside a
37980 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e ssert() statemen
37990 74 73 2e 20 7b 48 31 37 30 38 31 7d 20 54 68 65 ts. {H17081} The
379a0 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 SQLite core.**
379b0 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 73 65 never uses these
379c0 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 routines except
379d0 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 inside an asser
379e0 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 t() and applicat
379f0 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 ions.** are advi
37a00 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 sed to follow th
37a10 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f e lead of the co
37a20 72 65 2e 20 20 7b 48 31 37 30 38 32 7d 20 54 68 re. {H17082} Th
37a30 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 e core only.** p
37a40 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e rovides implemen
37a50 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 tations for thes
37a60 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 e routines when
37a70 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a it is compiled.*
37a80 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 * with the SQLIT
37a90 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20 7b E_DEBUG flag. {
37aa0 41 31 37 30 38 37 7d 20 45 78 74 65 72 6e 61 6c A17087} External
37ab0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 mutex implement
37ac0 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e ations.** are on
37ad0 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 ly required to p
37ae0 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 rovide these rou
37af0 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f tines if SQLITE_
37b00 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 DEBUG is.** defi
37b10 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 ned and if NDEBU
37b20 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 G is not defined
37b30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d ..**.** {H17083}
37b40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
37b50 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 should return tr
37b60 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 ue if the mutex
37b70 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e in their argumen
37b80 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 t.** is held or
37b90 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 not held, respec
37ba0 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 tively, by the c
37bb0 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a alling thread..*
37bc0 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 *.** {X17084} Th
37bd0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
37be0 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 is not required
37bf0 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 to provided ver
37c00 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a sions of these.*
37c10 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 * routines that
37c20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 actually work. I
37c30 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 f the implementa
37c40 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 tion does not pr
37c50 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a ovide working.**
37c60 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 versions of the
37c70 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 se routines, it
37c80 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 should at least
37c90 70 72 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 provide stubs th
37ca0 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 at always.** ret
37cb0 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 urn true so that
37cc0 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 one does not ge
37cd0 74 20 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 t spurious asser
37ce0 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a tion failures..*
37cf0 2a 0a 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 *.** {H17085} If
37d00 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
37d10 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 sqlite3_mutex_h
37d20 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 eld() is a NULL
37d30 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 pointer then.**
37d40 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 the routine shou
37d50 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 ld return 1. {E
37d60 4e 44 7d 20 54 68 69 73 20 73 65 65 6d 73 20 63 ND} This seems c
37d70 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 ounter-intuitive
37d80 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c since.** clearl
37d90 79 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e y the mutex cann
37da0 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 ot be held if it
37db0 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e does not exist.
37dc0 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 But the.** the
37dd0 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 reason the mute
37de0 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 x does not exist
37df0 20 69 73 20 62 65 63 61 75 73 65 20 74 68 65 20 is because the
37e00 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 build is not.**
37e10 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 using mutexes.
37e20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 And we do not wa
37e30 6e 74 20 74 68 65 20 61 73 73 65 72 74 28 29 20 nt the assert()
37e40 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a containing the.*
37e50 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 * call to sqlite
37e60 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 3_mutex_held() t
37e70 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e o fail, so a non
37e80 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a -zero return is.
37e90 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 ** the appropria
37ea0 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 te thing to do.
37eb0 20 7b 48 31 37 30 38 36 7d 20 54 68 65 20 73 71 {H17086} The sq
37ec0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 lite3_mutex_noth
37ed0 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 eld().** interfa
37ee0 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 ce should also r
37ef0 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 eturn 1 when giv
37f00 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 en a NULL pointe
37f10 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 r..*/.SQLITE_API
37f20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 int sqlite3_mut
37f30 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f ex_held(sqlite3_
37f40 6d 75 74 65 78 2a 29 3b 0a 53 51 4c 49 54 45 5f mutex*);.SQLITE_
37f50 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
37f60 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 mutex_notheld(sq
37f70 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a lite3_mutex*);..
37f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
37f90 4d 75 74 65 78 20 54 79 70 65 73 20 7b 48 31 37 Mutex Types {H17
37fa0 30 30 31 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 001} <H17000>.**
37fb0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
37fc0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 _mutex_alloc()]
37fd0 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 interface takes
37fe0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
37ff0 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e t.** which is on
38000 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 e of these integ
38010 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a er constants..**
38020 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f 66 20 73 .** The set of s
38030 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 6d 61 tatic mutexes ma
38040 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e y change from on
38050 65 20 53 51 4c 69 74 65 20 72 65 6c 65 61 73 65 e SQLite release
38060 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e to the.** next.
38070 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 Applications t
38080 68 61 74 20 6f 76 65 72 72 69 64 65 20 74 68 65 hat override the
38090 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 built-in mutex
380a0 6c 6f 67 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a logic must be.**
380b0 20 70 72 65 70 61 72 65 64 20 74 6f 20 61 63 63 prepared to acc
380c0 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69 74 69 6f ommodate additio
380d0 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 nal static mutex
380e0 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 es..*/.#define S
380f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
38100 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 0.#
38110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
38120 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 TEX_RECURSIVE
38130 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
38140 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
38150 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 IC_MASTER 2.#
38160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
38170 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 TEX_STATIC_MEM
38180 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 3 /* sqlit
38190 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 e3_malloc() */.#
381a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
381b0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 TEX_STATIC_MEM2
381c0 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 4 /* NOT U
381d0 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 SED */.#define S
381e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
381f0 49 43 5f 4f 50 45 4e 20 20 20 20 20 20 34 20 20 IC_OPEN 4
38200 2f 2a 20 73 71 6c 69 74 65 33 42 74 72 65 65 4f /* sqlite3BtreeO
38210 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 pen() */.#define
38220 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
38230 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 ATIC_PRNG 5
38240 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e /* sqlite3_ran
38250 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 dom() */.#define
38260 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
38270 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36 ATIC_LRU 6
38280 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 /* lru page li
38290 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 st */.#define SQ
382a0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
382b0 43 5f 4c 52 55 32 20 20 20 20 20 20 37 20 20 2f C_LRU2 7 /
382c0 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 * lru page list
382d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
382e0 45 46 3a 20 52 65 74 72 69 65 76 65 20 74 68 65 EF: Retrieve the
382f0 20 6d 75 74 65 78 20 66 6f 72 20 61 20 64 61 74 mutex for a dat
38300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
38310 20 7b 48 31 37 30 30 32 7d 20 3c 48 31 37 30 30 {H17002} <H1700
38320 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 0>.**.** This in
38330 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
38340 61 20 70 6f 69 6e 74 65 72 20 74 68 65 20 5b 73 a pointer the [s
38350 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 qlite3_mutex] ob
38360 6a 65 63 74 20 74 68 61 74 20 0a 2a 2a 20 73 65 ject that .** se
38370 72 69 61 6c 69 7a 65 73 20 61 63 63 65 73 73 20 rializes access
38380 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 to the [database
38390 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 67 69 76 connection] giv
383a0 65 6e 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 en in the argume
383b0 6e 74 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 5b nt.** when the [
383c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
383d0 69 73 20 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a is Serialized..*
383e0 2a 20 49 66 20 74 68 65 20 5b 74 68 72 65 61 64 * If the [thread
383f0 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e ing mode] is Sin
38400 67 6c 65 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 gle-thread or Mu
38410 6c 74 69 2d 74 68 72 65 61 64 20 74 68 65 6e 20 lti-thread then
38420 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 this.** routine
38430 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
38440 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 ointer..*/.SQLIT
38450 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 6d 75 E_API sqlite3_mu
38460 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f tex *sqlite3_db_
38470 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29 3b mutex(sqlite3*);
38480 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
38490 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 : Low-Level Cont
384a0 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65 20 rol Of Database
384b0 46 69 6c 65 73 20 7b 48 31 31 33 30 30 7d 20 3c Files {H11300} <
384c0 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 S30800>.**.** {H
384d0 31 31 33 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 11301} The [sqli
384e0 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
384f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61 ()] interface ma
38500 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61 6c kes a direct cal
38510 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c l to the.** xFil
38520 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
38530 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 for the [sqlite3
38540 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
38550 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a 2a ect associated.*
38560 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 * with a particu
38570 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64 65 lar database ide
38580 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 ntified by the s
38590 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 econd argument.
385a0 7b 48 31 31 33 30 32 7d 20 54 68 65 0a 2a 2a 20 {H11302} The.**
385b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
385c0 62 61 73 65 20 69 73 20 74 68 65 20 6e 61 6d 65 base is the name
385d0 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65 assigned to the
385e0 20 64 61 74 61 62 61 73 65 20 62 79 20 74 68 65 database by the
385f0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e .** <a href="lan
38600 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 g_attach.html">A
38610 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f TTACH</a> SQL co
38620 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 mmand that opene
38630 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 d the.** databas
38640 65 2e 20 7b 48 31 31 33 30 33 7d 20 54 6f 20 63 e. {H11303} To c
38650 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20 ontrol the main
38660 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 75 database file, u
38670 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 se the name "mai
38680 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 n".** or a NULL
38690 70 6f 69 6e 74 65 72 2e 20 7b 48 31 31 33 30 34 pointer. {H11304
386a0 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 } The third and
386b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
386c0 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e s to this routin
386d0 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 e.** are passed
386e0 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 directly through
386f0 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 to the second a
38700 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 nd third paramet
38710 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 ers of.** the xF
38720 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
38730 64 2e 20 20 7b 48 31 31 33 30 35 7d 20 54 68 65 d. {H11305} The
38740 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
38750 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
38760 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f l.** method beco
38770 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 mes the return v
38780 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 alue of this rou
38790 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 tine..**.** {H11
387a0 33 30 36 7d 20 49 66 20 74 68 65 20 73 65 63 6f 306} If the seco
387b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 nd parameter (zD
387c0 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 bName) does not
387d0 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f match the name o
387e0 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 f any.** open da
387f0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 tabase file, the
38800 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 n SQLITE_ERROR i
38810 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 48 31 31 s returned. {H11
38820 33 30 37 7d 20 54 68 69 73 20 65 72 72 6f 72 0a 307} This error.
38830 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 ** code is not r
38840 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69 emembered and wi
38850 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c ll not be recall
38860 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 ed by [sqlite3_e
38870 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 rrcode()].** or
38880 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
38890 29 5d 2e 20 7b 41 31 31 33 30 38 7d 20 54 68 65 )]. {A11308} The
388a0 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c underlying xFil
388b0 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
388c0 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 might.** also re
388d0 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f turn SQLITE_ERRO
388e0 52 2e 20 20 7b 41 31 31 33 30 39 7d 20 54 68 65 R. {A11309} The
388f0 72 65 20 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 re is no way to
38900 64 69 73 74 69 6e 67 75 69 73 68 20 62 65 74 77 distinguish betw
38910 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 een.** an incorr
38920 65 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 ect zDbName and
38930 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 an SQLITE_ERROR
38940 72 65 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 return from the
38950 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 underlying.** xF
38960 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
38970 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 d. {END}.**.** S
38980 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
38990 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
389a0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
389b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 int sqlite3_file
389c0 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 _control(sqlite3
389d0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
389e0 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 DbName, int op,
389f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
38a00 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 API3REF: Testing
38a10 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34 Interface {H114
38a20 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 00} <S30800>.**.
38a30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 ** The sqlite3_t
38a40 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e est_control() in
38a50 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
38a60 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65 to read out inte
38a70 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 rnal.** state of
38a80 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 SQLite and to i
38a90 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74 nject faults int
38aa0 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73 o SQLite for tes
38ab0 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 ting.** purposes
38ac0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
38ad0 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 ameter is an ope
38ae0 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 ration code that
38af0 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 determines.** t
38b00 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 he number, meani
38b10 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f ng, and operatio
38b20 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75 n of all subsequ
38b30 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a ent parameters..
38b40 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
38b50 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 face is not for
38b60 75 73 65 20 62 79 20 61 70 70 6c 69 63 61 74 69 use by applicati
38b70 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73 20 ons. It exists
38b80 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 solely.** for ve
38b90 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72 rifying the corr
38ba0 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 ect operation of
38bb0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
38bc0 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a ary. Depending.
38bd0 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 ** on how the SQ
38be0 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 Lite library is
38bf0 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69 compiled, this i
38c00 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e nterface might n
38c10 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 ot exist..**.**
38c20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 The details of t
38c30 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 he operation cod
38c40 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e es, their meanin
38c50 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65 gs, the paramete
38c60 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c rs.** they take,
38c70 20 61 6e 64 20 77 68 61 74 20 74 68 65 79 20 64 and what they d
38c80 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 o are all subjec
38c90 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 t to change with
38ca0 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 out notice..** U
38cb0 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 nlike most of th
38cc0 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68 e SQLite API, th
38cd0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e is function is n
38ce0 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f ot guaranteed to
38cf0 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 .** operate cons
38d00 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e istently from on
38d10 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 e release to the
38d20 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 next..*/.SQLITE
38d30 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
38d40 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 69 6e _test_control(in
38d50 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a t op, ...);../*.
38d60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 ** CAPI3REF: Tes
38d70 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 20 4f ting Interface O
38d80 70 65 72 61 74 69 6f 6e 20 43 6f 64 65 73 20 7b peration Codes {
38d90 48 31 31 34 31 30 7d 20 3c 48 31 31 34 30 30 3e H11410} <H11400>
38da0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
38db0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 76 stants are the v
38dc0 61 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e 20 63 alid operation c
38dd0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 73 20 75 ode parameters u
38de0 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 20 66 69 sed.** as the fi
38df0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
38e00 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f [sqlite3_test_co
38e10 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 ntrol()]..**.**
38e20 54 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 These parameters
38e30 20 61 6e 64 20 74 68 65 69 72 20 6d 65 61 6e 69 and their meani
38e40 6e 67 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 ngs are subject
38e50 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77 69 74 to change.** wit
38e60 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20 54 68 hout notice. Th
38e70 65 73 65 20 76 61 6c 75 65 73 20 61 72 65 20 66 ese values are f
38e80 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72 70 6f or testing purpo
38e90 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 70 70 ses only..** App
38ea0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
38eb0 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f 66 20 not use any of
38ec0 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 these parameters
38ed0 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 or the.** [sqli
38ee0 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c te3_test_control
38ef0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
38f00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
38f10 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 53 _TESTCTRL_PRNG_S
38f20 41 56 45 20 20 20 20 20 20 20 20 20 20 20 20 20 AVE
38f30 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
38f40 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e ITE_TESTCTRL_PRN
38f50 47 5f 52 45 53 54 4f 52 45 20 20 20 20 20 20 20 G_RESTORE
38f60 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 6.#define
38f70 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
38f80 50 52 4e 47 5f 52 45 53 45 54 20 20 20 20 20 20 PRNG_RESET
38f90 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 7.#defi
38fa0 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
38fb0 52 4c 5f 42 49 54 56 45 43 5f 54 45 53 54 20 20 RL_BITVEC_TEST
38fc0 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 8.#d
38fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
38fe0 54 43 54 52 4c 5f 46 41 55 4c 54 5f 49 4e 53 54 TCTRL_FAULT_INST
38ff0 41 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 39 ALL 9
39000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
39010 54 45 53 54 43 54 52 4c 5f 42 45 4e 49 47 4e 5f TESTCTRL_BENIGN_
39020 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20 20 20 MALLOC_HOOKS
39030 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 10.#define SQLI
39040 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 45 4e 44 TE_TESTCTRL_PEND
39050 49 4e 47 5f 42 59 54 45 20 20 20 20 20 20 20 20 ING_BYTE
39060 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 11.#define S
39070 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 41 QLITE_TESTCTRL_A
39080 53 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 SSERT
39090 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 12.#defin
390a0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 e SQLITE_TESTCTR
390b0 4c 5f 41 4c 57 41 59 53 20 20 20 20 20 20 20 20 L_ALWAYS
390c0 20 20 20 20 20 20 20 20 20 20 31 33 0a 23 64 65 13.#de
390d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
390e0 43 54 52 4c 5f 52 45 53 45 52 56 45 20 20 20 20 CTRL_RESERVE
390f0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 14.
39100 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
39110 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 SQLite Runtime
39120 53 74 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20 Status {H17200}
39130 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 <S60200>.** EXPE
39140 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
39150 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
39160 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
39170 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 e runtime status
39180 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
39190 61 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 about the prefor
391a0 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c mance of SQLite,
391b0 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 and optionally
391c0 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 to reset various
391d0 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 .** highwater ma
391e0 72 6b 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 rks. The first
391f0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
39200 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a nteger code for.
39210 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 20 ** the specific
39220 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 parameter to mea
39230 73 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 sure. Recognize
39240 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a d integer codes.
39250 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f ** are of the fo
39260 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 rm [SQLITE_STATU
39270 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 S_MEMORY_USED |
39280 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e SQLITE_STATUS_..
39290 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 .]..** The curre
392a0 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 nt value of the
392b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 parameter is ret
392c0 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 urned into *pCur
392d0 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 rent..** The hig
392e0 68 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 hest recorded va
392f0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 lue is returned
39300 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 in *pHighwater.
39310 20 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 If the.** reset
39320 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 68 Flag is true, th
39330 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 72 en the highest r
39340 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72 ecord value is r
39350 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 eset after.** *p
39360 48 69 67 68 77 61 74 65 72 20 69 73 20 77 72 69 Highwater is wri
39370 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d tten. Some param
39380 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 eters do not rec
39390 6f 72 64 20 74 68 65 20 68 69 67 68 65 73 74 0a ord the highest.
393a0 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 ** value. For t
393b0 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a hose parameters.
393c0 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 ** nothing is wr
393d0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 itten into *pHig
393e0 68 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 hwater and the r
393f0 65 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f esetFlag is igno
39400 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61 red..** Other pa
39410 72 61 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20 rameters record
39420 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 77 61 74 only the highwat
39430 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 er mark and not
39440 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 the current.** v
39450 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65 alue. For these
39460 20 6c 61 74 74 65 72 20 70 61 72 61 6d 65 74 65 latter paramete
39470 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 rs nothing is wr
39480 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 itten into *pCur
39490 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 rent..**.** This
394a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
394b0 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 SQLITE_OK on su
394c0 63 63 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d ccess and a non-
394d0 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 zero.** [error c
394e0 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e ode] on failure.
394f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
39500 69 6e 65 20 69 73 20 74 68 72 65 61 64 73 61 66 ine is threadsaf
39510 65 20 62 75 74 20 69 73 20 6e 6f 74 20 61 74 6f e but is not ato
39520 6d 69 63 2e 20 20 54 68 69 73 20 72 6f 75 74 69 mic. This routi
39530 6e 65 20 63 61 6e 20 62 65 0a 2a 2a 20 63 61 6c ne can be.** cal
39540 6c 65 64 20 77 68 69 6c 65 20 6f 74 68 65 72 20 led while other
39550 74 68 72 65 61 64 73 20 61 72 65 20 72 75 6e 6e threads are runn
39560 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6f 72 20 ing the same or
39570 64 69 66 66 65 72 65 6e 74 20 53 51 4c 69 74 65 different SQLite
39580 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 20 .** interfaces.
39590 20 48 6f 77 65 76 65 72 20 74 68 65 20 76 61 6c However the val
395a0 75 65 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 ues returned in
395b0 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 0a 2a 2a *pCurrent and.**
395c0 20 2a 70 48 69 67 68 77 61 74 65 72 20 72 65 66 *pHighwater ref
395d0 6c 65 63 74 20 74 68 65 20 73 74 61 74 75 73 20 lect the status
395e0 6f 66 20 53 51 4c 69 74 65 20 61 74 20 64 69 66 of SQLite at dif
395f0 66 65 72 65 6e 74 20 70 6f 69 6e 74 73 20 69 6e ferent points in
39600 20 74 69 6d 65 0a 2a 2a 20 61 6e 64 20 69 74 20 time.** and it
39610 69 73 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74 is possible that
39620 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
39630 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 might change the
39640 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e parameter.** in
39650 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 69 6d between the tim
39660 65 73 20 77 68 65 6e 20 2a 70 43 75 72 72 65 6e es when *pCurren
39670 74 20 61 6e 64 20 2a 70 48 69 67 68 77 61 74 65 t and *pHighwate
39680 72 20 61 72 65 20 77 72 69 74 74 65 6e 2e 0a 2a r are written..*
39690 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
396a0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 sqlite3_db_statu
396b0 73 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 s()].*/.SQLITE_A
396c0 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 PI SQLITE_EXPERI
396d0 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
396e0 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f 70 e3_status(int op
396f0 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74 2c , int *pCurrent,
39700 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65 72 int *pHighwater
39710 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 , int resetFlag)
39720 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
39730 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d EF: Status Param
39740 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d 20 3c eters {H17250} <
39750 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 H17200>.** EXPER
39760 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
39770 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 ese integer cons
39780 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 65 20 tants designate
39790 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d 65 various run-time
397a0 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 status paramete
397b0 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 rs.** that can b
397c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 e returned by [s
397d0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
397e0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
397f0 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 <dt>SQLITE_STATU
39800 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f 64 S_MEMORY_USED</d
39810 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
39820 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
39830 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20 6f current amount o
39840 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65 64 f memory checked
39850 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 out.** using [s
39860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
39870 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 74 6c , either directl
39880 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c 79 2e y or indirectly.
39890 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 65 20 The.** figure
398a0 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 20 6d includes calls m
398b0 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ade to [sqlite3_
398c0 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68 65 malloc()] by the
398d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
398e0 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d and internal mem
398f0 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 68 65 ory usage by the
39900 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e SQLite library.
39910 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 Scratch memory
39920 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 .** controlled b
39930 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 y [SQLITE_CONFIG
39940 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 61 75 _SCRATCH] and au
39950 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 61 63 xiliary page-cac
39960 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f 6e he.** memory con
39970 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49 trolled by [SQLI
39980 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
39990 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63 6c CHE] is not incl
399a0 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73 20 uded in.** this
399b0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 parameter. The
399c0 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 amount returned
399d0 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 74 68 is the sum of th
399e0 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 e allocation.**
399f0 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 74 65 sizes as reporte
39a00 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 20 6d d by the xSize m
39a10 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74 65 ethod in [sqlite
39a20 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e 3c 3_mem_methods].<
39a30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
39a40 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c QLITE_STATUS_MAL
39a50 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a LOC_SIZE</dt>.**
39a60 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
39a70 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 ter records the
39a80 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 largest memory a
39a90 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 llocation reques
39aa0 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b t.** handed to [
39ab0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
39ac0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
39ad0 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68 65 alloc()] (or the
39ae0 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 65 ir.** internal e
39af0 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f 6e quivalents). On
39b00 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ly the value ret
39b10 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 urned in the.**
39b20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61 *pHighwater para
39b30 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
39b40 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f 3_status()] is o
39b50 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a f interest. .**
39b60 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74 The value writt
39b70 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 en into the *pCu
39b80 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20 rrent parameter
39b90 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 is undefined.</d
39ba0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
39bb0 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 ITE_STATUS_PAGEC
39bc0 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a ACHE_USED</dt>.*
39bd0 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
39be0 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 eter returns the
39bf0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 number of pages
39c00 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65 used out of the
39c10 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 20 6d .** [pagecache m
39c20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
39c30 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66 69 67 that was config
39c40 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a 20 5b ured using .** [
39c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
39c60 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65 0a 2a GECACHE]. The.*
39c70 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 * value returned
39c80 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20 6e 6f is in pages, no
39c90 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e t in bytes.</dd>
39ca0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
39cb0 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 E_STATUS_PAGECAC
39cc0 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e HE_OVERFLOW</dt>
39cd0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
39ce0 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 ameter returns t
39cf0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
39d00 65 73 20 6f 66 20 70 61 67 65 20 63 61 63 68 65 es of page cache
39d10 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 .** allocation w
39d20 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 hich could not b
39d30 65 20 73 74 61 74 69 73 66 69 65 64 20 62 79 20 e statisfied by
39d40 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
39d50 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a 2a 2a IG_PAGECACHE].**
39d60 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 65 72 buffer and wher
39d70 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 e forced to over
39d80 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 flow to [sqlite3
39d90 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 _malloc()]. The
39da0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 61 6c .** returned val
39db0 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 6f ue includes allo
39dc0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 cations that ove
39dd0 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 20 rflowed because
39de0 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 74 6f they.** where to
39df0 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20 77 65 o large (they we
39e00 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 re larger than t
39e10 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65 he "sz" paramete
39e20 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f r to.** [SQLITE_
39e30 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
39e40 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 69 6f ]) and allocatio
39e50 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 ns that overflow
39e60 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 6e 6f ed because.** no
39e70 20 73 70 61 63 65 20 77 61 73 20 6c 65 66 74 20 space was left
39e80 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68 in the page cach
39e90 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
39ea0 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f t>SQLITE_STATUS_
39eb0 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 3c 2f PAGECACHE_SIZE</
39ec0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
39ed0 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 parameter record
39ee0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 s the largest me
39ef0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
39f00 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 request.** hande
39f10 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68 65 20 d to [pagecache
39f20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
39f30 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c ]. Only the val
39f40 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 ue returned in t
39f50 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 he.** *pHighwate
39f60 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b r parameter to [
39f70 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 sqlite3_status()
39f80 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 ] is of interest
39f90 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 . .** The value
39fa0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
39fb0 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 e *pCurrent para
39fc0 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e meter is undefin
39fd0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
39fe0 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
39ff0 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c 2f 64 _SCRATCH_USED</d
3a000 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
3a010 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 arameter returns
3a020 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 the number of a
3a030 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 64 20 llocations used
3a040 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 out of the.** [s
3a050 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c cratch memory al
3a060 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 locator] configu
3a070 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 51 red using.** [SQ
3a080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
3a090 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 TCH]. The value
3a0a0 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e 20 returned is in
3a0b0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f 74 allocations, not
3a0c0 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 20 53 .** in bytes. S
3a0d0 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 74 68 ince a single th
3a0e0 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 68 61 read may only ha
3a0f0 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68 20 61 ve one scratch a
3a100 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75 74 llocation.** out
3a110 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69 6d 65 standing at time
3a120 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 , this parameter
3a130 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 74 68 also reports th
3a140 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 e number of thre
3a150 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 63 72 ads.** using scr
3a160 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 20 74 atch memory at t
3a170 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f 64 he same time.</d
3a180 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
3a190 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 ITE_STATUS_SCRAT
3a1a0 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e CH_OVERFLOW</dt>
3a1b0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
3a1c0 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 ameter returns t
3a1d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
3a1e0 65 73 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 es of scratch me
3a1f0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 mory.** allocati
3a200 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e on which could n
3a210 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65 64 ot be statisfied
3a220 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f by the [SQLITE_
3a230 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 0a CONFIG_SCRATCH].
3a240 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 ** buffer and wh
3a250 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 ere forced to ov
3a260 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 erflow to [sqlit
3a270 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 e3_malloc()]. T
3a280 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 65 74 he values.** ret
3a290 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 6f 76 urned include ov
3a2a0 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73 65 20 erflows because
3a2b0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61 6c the requested al
3a2c0 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 6f 6f location was too
3a2d0 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 61 74 .** larger (that
3a2e0 20 69 73 2c 20 62 65 63 61 75 73 65 20 74 68 65 is, because the
3a2f0 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 requested alloc
3a300 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 65 72 ation was larger
3a310 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 73 7a than the.** "sz
3a320 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b " parameter to [
3a330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
3a340 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65 63 61 RATCH]) and beca
3a350 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68 20 62 use no scratch b
3a360 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 20 77 uffer.** slots w
3a370 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a ere available..*
3a380 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 * </dd>.**.** <d
3a390 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f t>SQLITE_STATUS_
3a3a0 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f 64 74 SCRATCH_SIZE</dt
3a3b0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
3a3c0 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 rameter records
3a3d0 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f the largest memo
3a3e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
3a3f0 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 quest.** handed
3a400 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f to [scratch memo
3a410 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 ry allocator].
3a420 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 Only the value r
3a430 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a eturned in the.*
3a440 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 * *pHighwater pa
3a450 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
3a460 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 te3_status()] is
3a470 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a of interest. .
3a480 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 ** The value wri
3a490 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 tten into the *p
3a4a0 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 Current paramete
3a4b0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c r is undefined.<
3a4c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
3a4d0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 52 QLITE_STATUS_PAR
3a4e0 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a 2a SER_STACK</dt>.*
3a4f0 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
3a500 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 eter records the
3a510 20 64 65 65 70 65 73 74 20 70 61 72 73 65 72 20 deepest parser
3a520 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20 6f 6e stack. It is on
3a530 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 75 6c ly.** meaningful
3a540 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
3a550 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59 59 54 mpiled with [YYT
3a560 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 50 54 RACKMAXSTACKDEPT
3a570 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c H].</dd>.** </dl
3a580 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 61 74 >.**.** New stat
3a590 75 73 20 70 61 72 61 6d 65 74 65 72 73 20 6d 61 us parameters ma
3a5a0 79 20 62 65 20 61 64 64 65 64 20 66 72 6f 6d 20 y be added from
3a5b0 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a 2a 2f time to time..*/
3a5c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3a5d0 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 STATUS_MEMORY_US
3a5e0 45 44 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 ED 0.#d
3a5f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 efine SQLITE_STA
3a600 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55 53 TUS_PAGECACHE_US
3a610 45 44 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 ED 1.#defi
3a620 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 ne SQLITE_STATUS
3a630 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52 46 _PAGECACHE_OVERF
3a640 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e 65 20 LOW 2.#define
3a650 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 SQLITE_STATUS_SC
3a660 52 41 54 43 48 5f 55 53 45 44 20 20 20 20 20 20 RATCH_USED
3a670 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
3a680 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 ITE_STATUS_SCRAT
3a690 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 20 20 CH_OVERFLOW
3a6a0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
3a6b0 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 _STATUS_MALLOC_S
3a6c0 49 5a 45 20 20 20 20 20 20 20 20 20 20 35 0a 23 IZE 5.#
3a6d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
3a6e0 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41 43 ATUS_PARSER_STAC
3a6f0 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 K 6.#def
3a700 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
3a710 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 S_PAGECACHE_SIZE
3a720 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
3a730 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 SQLITE_STATUS_S
3a740 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20 20 20 CRATCH_SIZE
3a750 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8../*.** CAP
3a760 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
3a770 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 74 75 Connection Statu
3a780 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 30 32 s {H17500} <S602
3a790 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
3a7a0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 TAL.**.** This i
3a7b0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
3a7c0 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e to retrieve run
3a7d0 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f time status info
3a7e0 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f 75 rmation .** abou
3a7f0 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 74 61 t a single [data
3a800 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3a810 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 . The first arg
3a820 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 ument is the.**
3a830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3a840 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 ion object to be
3a850 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 interrogated.
3a860 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
3a870 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 70 61 ent.** is the pa
3a880 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 65 72 rameter to inter
3a890 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65 6e 74 rogate. Current
3a8a0 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 6c 6c ly, the only all
3a8b0 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20 66 6f owed value.** fo
3a8c0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 r the second par
3a8d0 61 6d 65 74 65 72 20 69 73 20 5b 53 51 4c 49 54 ameter is [SQLIT
3a8e0 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 E_DBSTATUS_LOOKA
3a8f0 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20 41 SIDE_USED]..** A
3a900 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6f 6e dditional option
3a910 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 61 70 s will likely ap
3a920 70 65 61 72 20 69 6e 20 66 75 74 75 72 65 20 72 pear in future r
3a930 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
3a940 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 75 72 e..**.** The cur
3a950 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 rent value of th
3a960 65 20 72 65 71 75 65 73 74 65 64 20 70 61 72 61 e requested para
3a970 6d 65 74 65 72 20 69 73 20 77 72 69 74 74 65 6e meter is written
3a980 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a 20 61 into *pCur.** a
3a990 6e 64 20 74 68 65 20 68 69 67 68 65 73 74 20 69 nd the highest i
3a9a0 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c nstantaneous val
3a9b0 75 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e ue is written in
3a9c0 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 49 66 0a to *pHiwtr. If.
3a9d0 2a 2a 20 74 68 65 20 72 65 73 65 74 46 6c 67 20 ** the resetFlg
3a9e0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 is true, then th
3a9f0 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e e highest instan
3aa00 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73 taneous value is
3aa10 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 6b 20 64 .** reset back d
3aa20 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 72 72 65 own to the curre
3aa30 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 nt value..**.**
3aa40 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
3aa50 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 6e 64 e3_status()] and
3aa60 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 [sqlite3_stmt_s
3aa70 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 4c tatus()]..*/.SQL
3aa80 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 ITE_API SQLITE_E
3aa90 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 XPERIMENTAL int
3aaa0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 sqlite3_db_statu
3aab0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
3aac0 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 2c 20 69 op, int *pCur, i
3aad0 6e 74 20 2a 70 48 69 77 74 72 2c 20 69 6e 74 20 nt *pHiwtr, int
3aae0 72 65 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a resetFlg);../*.*
3aaf0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 74 * CAPI3REF: Stat
3ab00 75 73 20 50 61 72 61 6d 65 74 65 72 73 20 66 6f us Parameters fo
3ab10 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
3ab20 63 74 69 6f 6e 73 20 7b 48 31 37 35 32 30 7d 20 ctions {H17520}
3ab30 3c 48 31 37 35 30 30 3e 0a 2a 2a 20 45 58 50 45 <H17500>.** EXPE
3ab40 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
3ab50 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
3ab60 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 re the available
3ab70 20 69 6e 74 65 67 65 72 20 22 76 65 72 62 73 22 integer "verbs"
3ab80 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 73 that can be pas
3ab90 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 73 65 sed as.** the se
3aba0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
3abb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 the [sqlite3_db
3abc0 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65 72 _status()] inter
3abd0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
3abe0 76 65 72 62 73 20 6d 61 79 20 62 65 20 61 64 64 verbs may be add
3abf0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
3ac00 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
3ac10 20 45 78 69 73 74 69 6e 67 20 76 65 72 62 73 0a Existing verbs.
3ac20 2a 2a 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ** might be disc
3ac30 6f 6e 74 69 6e 75 65 64 2e 20 41 70 70 6c 69 63 ontinued. Applic
3ac40 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 63 68 ations should ch
3ac50 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
3ac60 6f 64 65 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c ode from.** [sql
3ac70 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 ite3_db_status()
3ac80 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
3ac90 68 61 74 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 hat the call wor
3aca0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ked..** The [sql
3acb0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 ite3_db_status()
3acc0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
3acd0 20 72 65 74 75 72 6e 20 61 20 6e 6f 6e 2d 7a 65 return a non-ze
3ace0 72 6f 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a ro error code.**
3acf0 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 if a discontinu
3ad00 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 ed or unsupporte
3ad10 64 20 76 65 72 62 20 69 73 20 69 6e 76 6f 6b 65 d verb is invoke
3ad20 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
3ad30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 53 54 <dt>SQLITE_DBST
3ad40 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 ATUS_LOOKASIDE_U
3ad50 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e SED</dt>.** <dd>
3ad60 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
3ad70 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
3ad80 72 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d r of lookaside m
3ad90 65 6d 6f 72 79 20 73 6c 6f 74 73 20 63 75 72 72 emory slots curr
3ada0 65 6e 74 6c 79 0a 2a 2a 20 63 68 65 63 6b 65 64 ently.** checked
3adb0 20 6f 75 74 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f out.</dd>.** </
3adc0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
3add0 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c QLITE_DBSTATUS_L
3ade0 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 20 20 20 OOKASIDE_USED
3adf0 20 20 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0.../*.** CAPI
3ae00 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 3REF: Prepared S
3ae10 74 61 74 65 6d 65 6e 74 20 53 74 61 74 75 73 20 tatement Status
3ae20 7b 48 31 37 35 35 30 7d 20 3c 53 36 30 32 30 30 {H17550} <S60200
3ae30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
3ae40 4c 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 70 72 65 L.**.** Each pre
3ae50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
3ae60 6d 61 69 6e 74 61 69 6e 73 20 76 61 72 69 6f 75 maintains variou
3ae70 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d s.** [SQLITE_STM
3ae80 54 53 54 41 54 55 53 5f 53 4f 52 54 20 7c 20 63 TSTATUS_SORT | c
3ae90 6f 75 6e 74 65 72 73 5d 20 74 68 61 74 20 6d 65 ounters] that me
3aea0 61 73 75 72 65 20 74 68 65 20 6e 75 6d 62 65 72 asure the number
3aeb0 0a 2a 2a 20 6f 66 20 74 69 6d 65 73 20 69 74 20 .** of times it
3aec0 68 61 73 20 70 65 72 66 6f 72 6d 65 64 20 73 70 has performed sp
3aed0 65 63 69 66 69 63 20 6f 70 65 72 61 74 69 6f 6e ecific operation
3aee0 73 2e 20 20 54 68 65 73 65 20 63 6f 75 6e 74 65 s. These counte
3aef0 72 73 20 63 61 6e 0a 2a 2a 20 62 65 20 75 73 65 rs can.** be use
3af00 64 20 74 6f 20 6d 6f 6e 69 74 6f 72 20 74 68 65 d to monitor the
3af10 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 63 68 61 performance cha
3af20 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 racteristics of
3af30 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 the prepared.**
3af40 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 46 6f 72 statements. For
3af50 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 example, if the
3af60 20 6e 75 6d 62 65 72 20 6f 66 20 74 61 62 6c 65 number of table
3af70 20 73 74 65 70 73 20 67 72 65 61 74 6c 79 20 65 steps greatly e
3af80 78 63 65 65 64 73 0a 2a 2a 20 74 68 65 20 6e 75 xceeds.** the nu
3af90 6d 62 65 72 20 6f 66 20 74 61 62 6c 65 20 73 65 mber of table se
3afa0 61 72 63 68 65 73 20 6f 72 20 72 65 73 75 6c 74 arches or result
3afb0 20 72 6f 77 73 2c 20 74 68 61 74 20 77 6f 75 6c rows, that woul
3afc0 64 20 74 65 6e 64 20 74 6f 20 69 6e 64 69 63 61 d tend to indica
3afd0 74 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 te.** that the p
3afe0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
3aff0 74 20 69 73 20 75 73 69 6e 67 20 61 20 66 75 6c t is using a ful
3b000 6c 20 74 61 62 6c 65 20 73 63 61 6e 20 72 61 74 l table scan rat
3b010 68 65 72 20 74 68 61 6e 0a 2a 2a 20 61 6e 20 69 her than.** an i
3b020 6e 64 65 78 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 ndex. .**.** Th
3b030 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
3b040 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 used to retrieve
3b050 20 61 6e 64 20 72 65 73 65 74 20 63 6f 75 6e 74 and reset count
3b060 65 72 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a er values from.*
3b070 2a 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 * a [prepared st
3b080 61 74 65 6d 65 6e 74 5d 2e 20 20 54 68 65 20 66 atement]. The f
3b090 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
3b0a0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
3b0b0 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 62 6a 65 63 atement.** objec
3b0c0 74 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 t to be interrog
3b0d0 61 74 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e ated. The secon
3b0e0 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 d argument.** is
3b0f0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 an integer code
3b100 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 63 20 for a specific
3b110 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 [SQLITE_STMTSTAT
3b120 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 US_SORT | counte
3b130 72 5d 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 r].** to be inte
3b140 72 72 6f 67 61 74 65 64 2e 20 0a 2a 2a 20 54 68 rrogated. .** Th
3b150 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
3b160 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 of the requested
3b170 20 63 6f 75 6e 74 65 72 20 69 73 20 72 65 74 75 counter is retu
3b180 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 rned..** If the
3b190 72 65 73 65 74 46 6c 67 20 69 73 20 74 72 75 65 resetFlg is true
3b1a0 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 75 6e 74 , then the count
3b1b0 65 72 20 69 73 20 72 65 73 65 74 20 74 6f 20 7a er is reset to z
3b1c0 65 72 6f 20 61 66 74 65 72 20 74 68 69 73 0a 2a ero after this.*
3b1d0 2a 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c * interface call
3b1e0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
3b1f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
3b200 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 6e 64 e3_status()] and
3b210 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 [sqlite3_db_sta
3b220 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 tus()]..*/.SQLIT
3b230 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 E_API SQLITE_EXP
3b240 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 ERIMENTAL int sq
3b250 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 lite3_stmt_statu
3b260 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c s(sqlite3_stmt*,
3b270 20 69 6e 74 20 6f 70 2c 69 6e 74 20 72 65 73 65 int op,int rese
3b280 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tFlg);../*.** CA
3b290 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 PI3REF: Status P
3b2a0 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 70 72 arameters for pr
3b2b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
3b2c0 73 20 7b 48 31 37 35 37 30 7d 20 3c 48 31 37 35 s {H17570} <H175
3b2d0 35 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 50>.** EXPERIMEN
3b2e0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TAL.**.** These
3b2f0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
3b300 72 6f 73 20 64 65 66 69 6e 65 20 69 6e 74 65 67 ros define integ
3b310 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 6e 61 er codes that na
3b320 6d 65 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 61 me counter.** va
3b330 6c 75 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 lues associated
3b340 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 with the [sqlite
3b350 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 3_stmt_status()]
3b360 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 interface..** T
3b370 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
3b380 68 65 20 76 61 72 69 6f 75 73 20 63 6f 75 6e 74 he various count
3b390 65 72 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f ers are as follo
3b3a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ws:.**.** <dl>.*
3b3b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d * <dt>SQLITE_STM
3b3c0 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e TSTATUS_FULLSCAN
3b3d0 5f 53 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _STEP</dt>.** <d
3b3e0 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 d>This is the nu
3b3f0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 mber of times th
3b400 61 74 20 53 51 4c 69 74 65 20 68 61 73 20 73 74 at SQLite has st
3b410 65 70 70 65 64 20 66 6f 72 77 61 72 64 20 69 6e epped forward in
3b420 0a 2a 2a 20 61 20 74 61 62 6c 65 20 61 73 20 70 .** a table as p
3b430 61 72 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 61 art of a full ta
3b440 62 6c 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 65 ble scan. Large
3b450 20 6e 75 6d 62 65 72 73 20 66 6f 72 20 74 68 69 numbers for thi
3b460 73 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 s counter.** may
3b470 20 69 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 74 indicate opport
3b480 75 6e 69 74 69 65 73 20 66 6f 72 20 70 65 72 66 unities for perf
3b490 6f 72 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 6d ormance improvem
3b4a0 65 6e 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a 20 ent through .**
3b4b0 63 61 72 65 66 75 6c 20 75 73 65 20 6f 66 20 69 careful use of i
3b4c0 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a ndices.</dd>.**.
3b4d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
3b4e0 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 3c 2f 64 MTSTATUS_SORT</d
3b4f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 t>.** <dd>This i
3b500 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
3b510 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 sort operations
3b520 74 68 61 74 20 68 61 76 65 20 6f 63 63 75 72 72 that have occurr
3b530 65 64 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 72 ed..** A non-zer
3b540 6f 20 76 61 6c 75 65 20 69 6e 20 74 68 69 73 20 o value in this
3b550 63 6f 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 69 counter may indi
3b560 63 61 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e cate an opportun
3b570 69 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f 76 ity to.** improv
3b580 65 6d 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e 63 ement performanc
3b590 65 20 74 68 72 6f 75 67 68 20 63 61 72 65 66 75 e through carefu
3b5a0 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 l use of indices
3b5b0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 .</dd>.**.** </d
3b5c0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
3b5d0 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
3b5e0 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 20 20 20 FULLSCAN_STEP
3b5f0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
3b600 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f TE_STMTSTATUS_SO
3b610 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 RT
3b620 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 2../*.** CAPI3RE
3b630 46 3a 20 43 75 73 74 6f 6d 20 50 61 67 65 20 43 F: Custom Page C
3b640 61 63 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 ache Object.** E
3b650 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
3b660 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 63 * The sqlite3_pc
3b670 61 63 68 65 20 74 79 70 65 20 69 73 20 6f 70 61 ache type is opa
3b680 71 75 65 2e 20 20 49 74 20 69 73 20 69 6d 70 6c que. It is impl
3b690 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 68 emented by.** th
3b6a0 65 20 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 75 e pluggable modu
3b6b0 6c 65 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 le. The SQLite
3b6c0 63 6f 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 core has no know
3b6d0 6c 65 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 20 ledge of.** its
3b6e0 73 69 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 6c size or internal
3b6f0 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 6e structure and n
3b700 65 76 65 72 20 64 65 61 6c 73 20 77 69 74 68 20 ever deals with
3b710 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 the.** sqlite3_p
3b720 63 61 63 68 65 20 6f 62 6a 65 63 74 20 65 78 63 cache object exc
3b730 65 70 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 61 ept by holding a
3b740 6e 64 20 70 61 73 73 69 6e 67 20 70 6f 69 6e 74 nd passing point
3b750 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f 62 ers.** to the ob
3b760 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ject..**.** See
3b770 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
3b780 6d 65 74 68 6f 64 73 5d 20 66 6f 72 20 61 64 64 methods] for add
3b790 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
3b7a0 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
3b7b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 struct sqlite3_p
3b7c0 63 61 63 68 65 20 73 71 6c 69 74 65 33 5f 70 63 cache sqlite3_pc
3b7d0 61 63 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ache;../*.** CAP
3b7e0 49 33 52 45 46 3a 20 41 70 70 6c 69 63 61 74 69 I3REF: Applicati
3b7f0 6f 6e 20 44 65 66 69 6e 65 64 20 50 61 67 65 20 on Defined Page
3b800 43 61 63 68 65 2e 0a 2a 2a 20 4b 45 59 57 4f 52 Cache..** KEYWOR
3b810 44 53 3a 20 7b 70 61 67 65 20 63 61 63 68 65 7d DS: {page cache}
3b820 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
3b830 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
3b840 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
3b850 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
3b860 45 5d 2c 20 2e 2e 2e 29 20 69 6e 74 65 72 66 61 E], ...) interfa
3b870 63 65 20 63 61 6e 0a 2a 2a 20 72 65 67 69 73 74 ce can.** regist
3b880 65 72 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 er an alternativ
3b890 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 e page cache imp
3b8a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 62 79 20 70 lementation by p
3b8b0 61 73 73 69 6e 67 20 69 6e 20 61 6e 20 0a 2a 2a assing in an .**
3b8c0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
3b8d0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
3b8e0 6d 65 74 68 6f 64 73 20 73 74 72 75 63 74 75 72 methods structur
3b8f0 65 2e 20 54 68 65 20 6d 61 6a 6f 72 69 74 79 20 e. The majority
3b900 6f 66 20 74 68 65 20 0a 2a 2a 20 68 65 61 70 20 of the .** heap
3b910 6d 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 53 memory used by S
3b920 51 4c 69 74 65 20 69 73 20 75 73 65 64 20 62 79 QLite is used by
3b930 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 20 the page cache
3b940 74 6f 20 63 61 63 68 65 20 64 61 74 61 20 72 65 to cache data re
3b950 61 64 20 0a 2a 2a 20 66 72 6f 6d 2c 20 6f 72 20 ad .** from, or
3b960 72 65 61 64 79 20 74 6f 20 62 65 20 77 72 69 74 ready to be writ
3b970 74 65 6e 20 74 6f 2c 20 74 68 65 20 64 61 74 61 ten to, the data
3b980 62 61 73 65 20 66 69 6c 65 2e 20 42 79 20 69 6d base file. By im
3b990 70 6c 65 6d 65 6e 74 69 6e 67 20 61 20 0a 2a 2a plementing a .**
3b9a0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 custom page cac
3b9b0 68 65 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 he using this AP
3b9c0 49 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f I, an applicatio
3b9d0 6e 20 63 61 6e 20 63 6f 6e 74 72 6f 6c 20 6d 6f n can control mo
3b9e0 72 65 20 0a 2a 2a 20 70 72 65 63 69 73 65 6c 79 re .** precisely
3b9f0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d the amount of m
3ba00 65 6d 6f 72 79 20 63 6f 6e 73 75 6d 65 64 20 62 emory consumed b
3ba10 79 20 53 51 4c 69 74 65 2c 20 74 68 65 20 77 61 y SQLite, the wa
3ba20 79 20 69 6e 20 77 68 69 63 68 20 0a 2a 2a 20 74 y in which .** t
3ba30 68 61 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c hat memory is al
3ba40 6c 6f 63 61 74 65 64 20 61 6e 64 20 72 65 6c 65 located and rele
3ba50 61 73 65 64 2c 20 61 6e 64 20 74 68 65 20 70 6f ased, and the po
3ba60 6c 69 63 69 65 73 20 75 73 65 64 20 74 6f 20 0a licies used to .
3ba70 2a 2a 20 64 65 74 65 72 6d 69 6e 65 20 65 78 61 ** determine exa
3ba80 63 74 6c 79 20 77 68 69 63 68 20 70 61 72 74 73 ctly which parts
3ba90 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 66 of a database f
3baa0 69 6c 65 20 61 72 65 20 63 61 63 68 65 64 20 61 ile are cached a
3bab0 6e 64 20 66 6f 72 20 0a 2a 2a 20 68 6f 77 20 6c nd for .** how l
3bac0 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ong..**.** The c
3bad0 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 73 ontents of the s
3bae0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
3baf0 74 68 6f 64 73 20 73 74 72 75 63 74 75 72 65 20 thods structure
3bb00 61 72 65 20 63 6f 70 69 65 64 20 74 6f 20 61 6e are copied to an
3bb10 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 62 75 66 .** internal buf
3bb20 66 65 72 20 62 79 20 53 51 4c 69 74 65 20 77 69 fer by SQLite wi
3bb30 74 68 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f thin the call to
3bb40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
3bb50 5d 2e 20 20 48 65 6e 63 65 0a 2a 2a 20 74 68 65 ]. Hence.** the
3bb60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 application may
3bb70 20 64 69 73 63 61 72 64 20 74 68 65 20 70 61 72 discard the par
3bb80 61 6d 65 74 65 72 20 61 66 74 65 72 20 74 68 65 ameter after the
3bb90 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
3bba0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 ite3_config()] r
3bbb0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 eturns..**.** Th
3bbc0 65 20 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 e xInit() method
3bbd0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 is called once
3bbe0 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f for each call to
3bbf0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
3bc00 6c 69 7a 65 28 29 5d 0a 2a 2a 20 28 75 73 75 61 lize()].** (usua
3bc10 6c 6c 79 20 6f 6e 6c 79 20 6f 6e 63 65 20 64 75 lly only once du
3bc20 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d ring the lifetim
3bc30 65 20 6f 66 20 74 68 65 20 70 72 6f 63 65 73 73 e of the process
3bc40 29 2e 20 49 74 20 69 73 20 70 61 73 73 65 64 0a ). It is passed.
3bc50 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ** a copy of the
3bc60 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
3bc70 6d 65 74 68 6f 64 73 2e 70 41 72 67 20 76 61 6c methods.pArg val
3bc80 75 65 2e 20 49 74 20 63 61 6e 20 62 65 20 75 73 ue. It can be us
3bc90 65 64 20 74 6f 20 73 65 74 0a 2a 2a 20 75 70 20 ed to set.** up
3bca0 67 6c 6f 62 61 6c 20 73 74 72 75 63 74 75 72 65 global structure
3bcb0 73 20 61 6e 64 20 6d 75 74 65 78 65 73 20 72 65 s and mutexes re
3bcc0 71 75 69 72 65 64 20 62 79 20 74 68 65 20 63 75 quired by the cu
3bcd0 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 stom page cache
3bce0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
3bcf0 6f 6e 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 on. .**.** The x
3bd00 53 68 75 74 64 6f 77 6e 28 29 20 6d 65 74 68 6f Shutdown() metho
3bd10 64 20 69 73 20 63 61 6c 6c 65 64 20 66 72 6f 6d d is called from
3bd20 20 77 69 74 68 69 6e 20 5b 73 71 6c 69 74 65 33 within [sqlite3
3bd30 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2c 20 0a 2a _shutdown()], .*
3bd40 2a 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 61 * if the applica
3bd50 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 74 68 69 tion invokes thi
3bd60 73 20 41 50 49 2e 20 49 74 20 63 61 6e 20 62 65 s API. It can be
3bd70 20 75 73 65 64 20 74 6f 20 63 6c 65 61 6e 20 75 used to clean u
3bd80 70 20 0a 2a 2a 20 61 6e 79 20 6f 75 74 73 74 61 p .** any outsta
3bd90 6e 64 69 6e 67 20 72 65 73 6f 75 72 63 65 73 20 nding resources
3bda0 62 65 66 6f 72 65 20 70 72 6f 63 65 73 73 20 73 before process s
3bdb0 68 75 74 64 6f 77 6e 2c 20 69 66 20 72 65 71 75 hutdown, if requ
3bdc0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ired..**.** SQLi
3bdd0 74 65 20 68 6f 6c 64 73 20 61 20 5b 53 51 4c 49 te holds a [SQLI
3bde0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
3bdf0 56 45 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 VE] mutex when i
3be00 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 t invokes.** the
3be10 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 xInit method, s
3be20 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 o the xInit meth
3be30 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 od need not be t
3be40 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a hreadsafe. The.
3be50 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 ** xShutdown met
3be60 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c hod is only call
3be70 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
3be80 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 _shutdown()] so
3be90 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e it does.** not n
3bea0 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 eed to be thread
3beb0 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 41 6c safe either. Al
3bec0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 20 l other methods
3bed0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
3bee0 66 65 0a 2a 2a 20 69 6e 20 6d 75 6c 74 69 74 68 fe.** in multith
3bef0 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 readed applicati
3bf00 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ons..**.** SQLit
3bf10 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 e will never inv
3bf20 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 oke xInit() more
3bf30 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f than once witho
3bf40 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e ut an intervenin
3bf50 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 g.** call to xSh
3bf60 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 utdown()..**.**
3bf70 54 68 65 20 78 43 72 65 61 74 65 28 29 20 6d 65 The xCreate() me
3bf80 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20 thod is used to
3bf90 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 construct a new
3bfa0 63 61 63 68 65 20 69 6e 73 74 61 6e 63 65 2e 20 cache instance.
3bfb0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 SQLite.** will
3bfc0 74 79 70 69 63 61 6c 6c 79 20 63 72 65 61 74 65 typically create
3bfd0 20 6f 6e 65 20 63 61 63 68 65 20 69 6e 73 74 61 one cache insta
3bfe0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 6f 70 65 nce for each ope
3bff0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c n database file,
3c000 0a 2a 2a 20 74 68 6f 75 67 68 20 74 68 69 73 20 .** though this
3c010 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 is not guarantee
3c020 64 2e 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 d. The.** first
3c030 70 61 72 61 6d 65 74 65 72 2c 20 73 7a 50 61 67 parameter, szPag
3c040 65 2c 20 69 73 20 74 68 65 20 73 69 7a 65 20 69 e, is the size i
3c050 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 70 n bytes of the p
3c060 61 67 65 73 20 74 68 61 74 20 6d 75 73 74 0a 2a ages that must.*
3c070 2a 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 * be allocated b
3c080 79 20 74 68 65 20 63 61 63 68 65 2e 20 20 73 7a y the cache. sz
3c090 50 61 67 65 20 77 69 6c 6c 20 6e 6f 74 20 62 65 Page will not be
3c0a0 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 2e a power of two.
3c0b0 20 20 73 7a 50 61 67 65 0a 2a 2a 20 77 69 6c 6c szPage.** will
3c0c0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 6f the page size o
3c0d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 f the database f
3c0e0 69 6c 65 20 74 68 61 74 20 69 73 20 74 6f 20 62 ile that is to b
3c0f0 65 20 63 61 63 68 65 64 20 70 6c 75 73 20 61 6e e cached plus an
3c100 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 20 28 68 .** increment (h
3c110 65 72 65 20 63 61 6c 6c 65 64 20 22 52 22 29 20 ere called "R")
3c120 6f 66 20 61 62 6f 75 74 20 31 30 30 20 6f 72 20 of about 100 or
3c130 32 30 30 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 200. SQLite wil
3c140 6c 20 75 73 65 20 74 68 65 0a 2a 2a 20 65 78 74 l use the.** ext
3c150 72 61 20 52 20 62 79 74 65 73 20 6f 6e 20 65 61 ra R bytes on ea
3c160 63 68 20 70 61 67 65 20 74 6f 20 73 74 6f 72 65 ch page to store
3c170 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 metadata about
3c180 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a the underlying.*
3c190 2a 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 * database page
3c1a0 6f 6e 20 64 69 73 6b 2e 20 20 54 68 65 20 76 61 on disk. The va
3c1b0 6c 75 65 20 6f 66 20 52 20 64 65 70 65 6e 64 73 lue of R depends
3c1c0 0a 2a 2a 20 6f 6e 20 74 68 65 20 53 51 4c 69 74 .** on the SQLit
3c1d0 65 20 76 65 72 73 69 6f 6e 2c 20 74 68 65 20 74 e version, the t
3c1e0 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 arget platform,
3c1f0 61 6e 64 20 68 6f 77 20 53 51 4c 69 74 65 20 77 and how SQLite w
3c200 61 73 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 20 as compiled..**
3c210 52 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 66 6f R is constant fo
3c220 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 62 r a particular b
3c230 75 69 6c 64 20 6f 66 20 53 51 4c 69 74 65 2e 20 uild of SQLite.
3c240 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
3c250 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 43 72 65 61 ment to.** xCrea
3c260 74 65 28 29 2c 20 62 50 75 72 67 65 61 62 6c 65 te(), bPurgeable
3c270 2c 20 69 73 20 74 72 75 65 20 69 66 20 74 68 65 , is true if the
3c280 20 63 61 63 68 65 20 62 65 69 6e 67 20 63 72 65 cache being cre
3c290 61 74 65 64 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 ated will.** be
3c2a0 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 used to cache da
3c2b0 74 61 62 61 73 65 20 70 61 67 65 73 20 6f 66 20 tabase pages of
3c2c0 61 20 66 69 6c 65 20 73 74 6f 72 65 64 20 6f 6e a file stored on
3c2d0 20 64 69 73 6b 2c 20 6f 72 0a 2a 2a 20 66 61 6c disk, or.** fal
3c2e0 73 65 20 69 66 20 69 74 20 69 73 20 75 73 65 64 se if it is used
3c2f0 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 for an in-memor
3c300 79 20 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 y database. The
3c310 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
3c320 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 tion.** does not
3c330 20 68 61 76 65 20 74 6f 20 64 6f 20 61 6e 79 74 have to do anyt
3c340 68 69 6e 67 20 73 70 65 63 69 61 6c 20 62 61 73 hing special bas
3c350 65 64 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 ed with the valu
3c360 65 20 6f 66 20 62 50 75 72 67 65 61 62 6c 65 3b e of bPurgeable;
3c370 0a 2a 2a 20 69 74 20 69 73 20 70 75 72 65 6c 79 .** it is purely
3c380 20 61 64 76 69 73 6f 72 79 2e 20 20 4f 6e 20 61 advisory. On a
3c390 20 63 61 63 68 65 20 77 68 65 72 65 20 62 50 75 cache where bPu
3c3a0 72 67 65 61 62 6c 65 20 69 73 20 66 61 6c 73 65 rgeable is false
3c3b0 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a , SQLite will.**
3c3c0 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 55 never invoke xU
3c3d0 6e 70 69 6e 28 29 20 65 78 63 65 70 74 20 74 6f npin() except to
3c3e0 20 64 65 6c 69 62 65 72 61 74 65 6c 79 20 64 65 deliberately de
3c3f0 6c 65 74 65 20 61 20 70 61 67 65 2e 0a 2a 2a 20 lete a page..**
3c400 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
3c410 61 20 63 61 63 68 65 20 63 72 65 61 74 65 64 20 a cache created
3c420 77 69 74 68 20 62 50 75 72 67 65 61 62 6c 65 20 with bPurgeable
3c430 73 65 74 20 74 6f 20 66 61 6c 73 65 20 77 69 6c set to false wil
3c440 6c 0a 2a 2a 20 6e 65 76 65 72 20 63 6f 6e 74 61 l.** never conta
3c450 69 6e 20 61 6e 79 20 75 6e 70 69 6e 6e 65 64 20 in any unpinned
3c460 70 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 pages..**.** The
3c470 20 78 43 61 63 68 65 73 69 7a 65 28 29 20 6d 65 xCachesize() me
3c480 74 68 6f 64 20 6d 61 79 20 62 65 20 63 61 6c 6c thod may be call
3c490 65 64 20 61 74 20 61 6e 79 20 74 69 6d 65 20 62 ed at any time b
3c4a0 79 20 53 51 4c 69 74 65 20 74 6f 20 73 65 74 20 y SQLite to set
3c4b0 74 68 65 0a 2a 2a 20 73 75 67 67 65 73 74 65 64 the.** suggested
3c4c0 20 6d 61 78 69 6d 75 6d 20 63 61 63 68 65 2d 73 maximum cache-s
3c4d0 69 7a 65 20 28 6e 75 6d 62 65 72 20 6f 66 20 70 ize (number of p
3c4e0 61 67 65 73 20 73 74 6f 72 65 64 20 62 79 29 20 ages stored by)
3c4f0 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 69 6e 73 the cache.** ins
3c500 74 61 6e 63 65 20 70 61 73 73 65 64 20 61 73 20 tance passed as
3c510 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
3c520 6e 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 nt. This is the
3c530 76 61 6c 75 65 20 63 6f 6e 66 69 67 75 72 65 64 value configured
3c540 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 53 51 using.** the SQ
3c550 4c 69 74 65 20 22 5b 50 52 41 47 4d 41 20 63 61 Lite "[PRAGMA ca
3c560 63 68 65 5f 73 69 7a 65 5d 22 20 63 6f 6d 6d 61 che_size]" comma
3c570 6e 64 2e 20 41 73 20 77 69 74 68 20 74 68 65 20 nd. As with the
3c580 62 50 75 72 67 65 61 62 6c 65 20 70 61 72 61 6d bPurgeable param
3c590 65 74 65 72 2c 0a 2a 2a 20 74 68 65 20 69 6d 70 eter,.** the imp
3c5a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e lementation is n
3c5b0 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 64 ot required to d
3c5c0 6f 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 20 o anything with
3c5d0 74 68 69 73 0a 2a 2a 20 76 61 6c 75 65 3b 20 69 this.** value; i
3c5e0 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e t is advisory on
3c5f0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 50 ly..**.** The xP
3c600 61 67 65 63 6f 75 6e 74 28 29 20 6d 65 74 68 6f agecount() metho
3c610 64 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 d should return
3c620 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 the number of pa
3c630 67 65 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a ges currently.**
3c640 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 stored in the c
3c650 61 63 68 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 ache..** .** The
3c660 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 6f 64 xFetch() method
3c670 20 69 73 20 75 73 65 64 20 74 6f 20 66 65 74 63 is used to fetc
3c680 68 20 61 20 70 61 67 65 20 61 6e 64 20 72 65 74 h a page and ret
3c690 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f urn a pointer to
3c6a0 20 69 74 2e 20 0a 2a 2a 20 41 20 27 70 61 67 65 it. .** A 'page
3c6b0 27 2c 20 69 6e 20 74 68 69 73 20 63 6f 6e 74 65 ', in this conte
3c6c0 78 74 2c 20 69 73 20 61 20 62 75 66 66 65 72 20 xt, is a buffer
3c6d0 6f 66 20 73 7a 50 61 67 65 20 62 79 74 65 73 20 of szPage bytes
3c6e0 61 6c 69 67 6e 65 64 20 61 74 20 61 6e 0a 2a 2a aligned at an.**
3c6f0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8-byte boundary
3c700 2e 20 54 68 65 20 70 61 67 65 20 74 6f 20 62 65 . The page to be
3c710 20 66 65 74 63 68 65 64 20 69 73 20 64 65 74 65 fetched is dete
3c720 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 6b 65 rmined by the ke
3c730 79 2e 20 54 68 65 0a 2a 2a 20 6d 69 6d 69 6d 75 y. The.** mimimu
3c740 6d 20 6b 65 79 20 76 61 6c 75 65 20 69 73 20 31 m key value is 1
3c750 2e 20 41 66 74 65 72 20 69 74 20 68 61 73 20 62 . After it has b
3c760 65 65 6e 20 72 65 74 72 69 65 76 65 64 20 75 73 een retrieved us
3c770 69 6e 67 20 78 46 65 74 63 68 2c 20 74 68 65 20 ing xFetch, the
3c780 70 61 67 65 20 0a 2a 2a 20 69 73 20 63 6f 6e 73 page .** is cons
3c790 69 64 65 72 65 64 20 74 6f 20 62 65 20 22 70 69 idered to be "pi
3c7a0 6e 6e 65 64 22 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 nned"..**.** If
3c7b0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70 61 the requested pa
3c7c0 67 65 20 69 73 20 61 6c 72 65 61 64 79 20 69 6e ge is already in
3c7d0 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2c the page cache,
3c7e0 20 74 68 65 6e 20 74 68 65 20 70 61 67 65 20 63 then the page c
3c7f0 61 63 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e ache.** implemen
3c800 74 61 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 tation must retu
3c810 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 rn a pointer to
3c820 74 68 65 20 70 61 67 65 20 62 75 66 66 65 72 20 the page buffer
3c830 77 69 74 68 20 69 74 73 20 63 6f 6e 74 65 6e 74 with its content
3c840 0a 2a 2a 20 69 6e 74 61 63 74 2e 20 20 49 66 20 .** intact. If
3c850 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70 61 the requested pa
3c860 67 65 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 ge is not alread
3c870 79 20 69 6e 20 74 68 65 20 63 61 63 68 65 2c 20 y in the cache,
3c880 74 68 65 6e 20 74 68 65 0a 2a 2a 20 62 65 68 61 then the.** beha
3c890 76 69 6f 72 20 6f 66 20 74 68 65 20 63 61 63 68 vior of the cach
3c8a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
3c8b0 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 is determined b
3c8c0 79 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 y the value of t
3c8d0 68 65 0a 2a 2a 20 63 72 65 61 74 65 46 6c 61 67 he.** createFlag
3c8e0 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 parameter passe
3c8f0 64 20 74 6f 20 78 46 65 74 63 68 2c 20 61 63 63 d to xFetch, acc
3c900 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 66 6f ording to the fo
3c910 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 3a 0a 2a llowing table:.*
3c920 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 *.** <table bord
3c930 65 72 3d 31 20 77 69 64 74 68 3d 38 35 25 20 61 er=1 width=85% a
3c940 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 2a 2a 20 lign=center>.**
3c950 3c 74 72 3e 3c 74 68 3e 20 63 72 65 61 74 65 46 <tr><th> createF
3c960 6c 61 67 20 3c 74 68 3e 20 42 65 68 61 76 69 6f lag <th> Behavio
3c970 75 72 20 77 68 65 6e 20 70 61 67 65 20 69 73 20 ur when page is
3c980 6e 6f 74 20 61 6c 72 65 61 64 79 20 69 6e 20 63 not already in c
3c990 61 63 68 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ache.** <tr><td>
3c9a0 20 30 20 3c 74 64 3e 20 44 6f 20 6e 6f 74 20 61 0 <td> Do not a
3c9b0 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 20 70 61 llocate a new pa
3c9c0 67 65 2e 20 20 52 65 74 75 72 6e 20 4e 55 4c 4c ge. Return NULL
3c9d0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 31 20 ..** <tr><td> 1
3c9e0 3c 74 64 3e 20 41 6c 6c 6f 63 61 74 65 20 61 20 <td> Allocate a
3c9f0 6e 65 77 20 70 61 67 65 20 69 66 20 69 74 20 65 new page if it e
3ca00 61 73 79 20 61 6e 64 20 63 6f 6e 76 65 6e 69 65 asy and convenie
3ca10 6e 74 20 74 6f 20 64 6f 20 73 6f 2e 0a 2a 2a 20 nt to do so..**
3ca20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ca30 4f 74 68 65 72 77 69 73 65 20 72 65 74 75 72 6e Otherwise return
3ca40 20 4e 55 4c 4c 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 NULL..** <tr><t
3ca50 64 3e 20 32 20 3c 74 64 3e 20 4d 61 6b 65 20 65 d> 2 <td> Make e
3ca60 76 65 72 79 20 65 66 66 6f 72 74 20 74 6f 20 61 very effort to a
3ca70 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 20 70 61 llocate a new pa
3ca80 67 65 2e 20 20 4f 6e 6c 79 20 72 65 74 75 72 6e ge. Only return
3ca90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
3caa0 20 20 20 20 4e 55 4c 4c 20 69 66 20 61 6c 6c 6f NULL if allo
3cab0 63 61 74 69 6e 67 20 61 20 6e 65 77 20 70 61 67 cating a new pag
3cac0 65 20 69 73 20 65 66 66 65 63 74 69 76 65 6c 79 e is effectively
3cad0 20 69 6d 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 impossible..**
3cae0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 53 </table>.**.** S
3caf0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 72 6d 61 QLite will norma
3cb00 6c 6c 79 20 69 6e 76 6f 6b 65 20 78 46 65 74 63 lly invoke xFetc
3cb10 68 28 29 20 77 69 74 68 20 61 20 63 72 65 61 74 h() with a creat
3cb20 65 46 6c 61 67 20 6f 66 20 30 20 6f 72 20 31 2e eFlag of 0 or 1.
3cb30 20 20 49 66 0a 2a 2a 20 61 20 63 61 6c 6c 20 74 If.** a call t
3cb40 6f 20 78 46 65 74 63 68 28 29 20 77 69 74 68 20 o xFetch() with
3cb50 63 72 65 61 74 65 46 6c 61 67 3d 3d 31 20 72 65 createFlag==1 re
3cb60 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e turns NULL, then
3cb70 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 SQLite will.**
3cb80 61 74 74 65 6d 70 74 20 74 6f 20 75 6e 70 69 6e attempt to unpin
3cb90 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 63 one or more cac
3cba0 68 65 20 70 61 67 65 73 20 62 79 20 73 70 69 6c he pages by spil
3cbb0 6c 69 6e 67 20 74 68 65 20 63 6f 6e 74 65 6e 74 ling the content
3cbc0 20 6f 66 0a 2a 2a 20 70 69 6e 6e 65 64 20 70 61 of.** pinned pa
3cbd0 67 65 73 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 ges to disk and
3cbe0 73 79 6e 63 68 69 6e 67 20 74 68 65 20 6f 70 65 synching the ope
3cbf0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 69 rating system di
3cc00 73 6b 20 63 61 63 68 65 2e 20 41 66 74 65 72 0a sk cache. After.
3cc10 2a 2a 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f ** attempting to
3cc20 20 75 6e 70 69 6e 20 70 61 67 65 73 2c 20 74 68 unpin pages, th
3cc30 65 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 6f e xFetch() metho
3cc40 64 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 d will be invoke
3cc50 64 20 61 67 61 69 6e 20 77 69 74 68 0a 2a 2a 20 d again with.**
3cc60 61 20 63 72 65 61 74 65 46 6c 61 67 20 6f 66 20 a createFlag of
3cc70 32 2e 0a 2a 2a 0a 2a 2a 20 78 55 6e 70 69 6e 28 2..**.** xUnpin(
3cc80 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 53 ) is called by S
3cc90 51 4c 69 74 65 20 77 69 74 68 20 61 20 70 6f 69 QLite with a poi
3cca0 6e 74 65 72 20 74 6f 20 61 20 63 75 72 72 65 6e nter to a curren
3ccb0 74 6c 79 20 70 69 6e 6e 65 64 20 70 61 67 65 0a tly pinned page.
3ccc0 2a 2a 20 61 73 20 69 74 73 20 73 65 63 6f 6e 64 ** as its second
3ccd0 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 74 68 argument. If th
3cce0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
3ccf0 72 2c 20 64 69 73 63 61 72 64 2c 20 69 73 20 6e r, discard, is n
3cd00 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e on-zero,.** then
3cd10 20 74 68 65 20 70 61 67 65 20 73 68 6f 75 6c 64 the page should
3cd20 20 62 65 20 65 76 69 63 74 65 64 20 66 72 6f 6d be evicted from
3cd30 20 74 68 65 20 63 61 63 68 65 2e 20 49 6e 20 74 the cache. In t
3cd40 68 69 73 20 63 61 73 65 20 53 51 4c 69 74 65 20 his case SQLite
3cd50 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 .** assumes that
3cd60 20 74 68 65 20 6e 65 78 74 20 74 69 6d 65 20 74 the next time t
3cd70 68 65 20 70 61 67 65 20 69 73 20 72 65 74 72 69 he page is retri
3cd80 65 76 65 64 20 66 72 6f 6d 20 74 68 65 20 63 61 eved from the ca
3cd90 63 68 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 che using.** the
3cda0 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 6f 64 xFetch() method
3cdb0 2c 20 69 74 20 77 69 6c 6c 20 62 65 20 7a 65 72 , it will be zer
3cdc0 6f 65 64 2e 20 49 66 20 74 68 65 20 64 69 73 63 oed. If the disc
3cdd0 61 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ard parameter is
3cde0 0a 2a 2a 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 .** zero, then t
3cdf0 68 65 20 70 61 67 65 20 69 73 20 63 6f 6e 73 69 he page is consi
3ce00 64 65 72 65 64 20 74 6f 20 62 65 20 75 6e 70 69 dered to be unpi
3ce10 6e 6e 65 64 2e 20 54 68 65 20 63 61 63 68 65 20 nned. The cache
3ce20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a implementation.*
3ce30 2a 20 6d 61 79 20 63 68 6f 6f 73 65 20 74 6f 20 * may choose to
3ce40 65 76 69 63 74 20 75 6e 70 69 6e 6e 65 64 20 70 evict unpinned p
3ce50 61 67 65 73 20 61 74 20 61 6e 79 20 74 69 6d 65 ages at any time
3ce60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 ..**.** The cach
3ce70 65 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 e is not require
3ce80 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 61 6e 79 d to perform any
3ce90 20 72 65 66 65 72 65 6e 63 65 20 63 6f 75 6e 74 reference count
3cea0 69 6e 67 2e 20 41 20 73 69 6e 67 6c 65 20 0a 2a ing. A single .*
3ceb0 2a 20 63 61 6c 6c 20 74 6f 20 78 55 6e 70 69 6e * call to xUnpin
3cec0 28 29 20 75 6e 70 69 6e 73 20 74 68 65 20 70 61 () unpins the pa
3ced0 67 65 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ge regardless of
3cee0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
3cef0 72 69 6f 72 20 63 61 6c 6c 73 20 0a 2a 2a 20 74 rior calls .** t
3cf00 6f 20 78 46 65 74 63 68 28 29 2e 0a 2a 2a 0a 2a o xFetch()..**.*
3cf10 2a 20 54 68 65 20 78 52 65 6b 65 79 28 29 20 6d * The xRekey() m
3cf20 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f ethod is used to
3cf30 20 63 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 change the key
3cf40 76 61 6c 75 65 20 61 73 73 6f 63 69 61 74 65 64 value associated
3cf50 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 70 61 67 with the.** pag
3cf60 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
3cf70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
3cf80 66 72 6f 6d 20 6f 6c 64 4b 65 79 20 74 6f 20 6e from oldKey to n
3cf90 65 77 4b 65 79 2e 20 49 66 20 74 68 65 20 63 61 ewKey. If the ca
3cfa0 63 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c che.** previousl
3cfb0 79 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20 65 6e y contains an en
3cfc0 74 72 79 20 61 73 73 6f 63 69 61 74 65 64 20 77 try associated w
3cfd0 69 74 68 20 6e 65 77 4b 65 79 2c 20 69 74 20 73 ith newKey, it s
3cfe0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 69 73 63 hould be.** disc
3cff0 61 72 64 65 64 2e 20 41 6e 79 20 70 72 69 6f 72 arded. Any prior
3d000 20 63 61 63 68 65 20 65 6e 74 72 79 20 61 73 73 cache entry ass
3d010 6f 63 69 61 74 65 64 20 77 69 74 68 20 6e 65 77 ociated with new
3d020 4b 65 79 20 69 73 20 67 75 61 72 61 6e 74 65 65 Key is guarantee
3d030 64 20 6e 6f 74 0a 2a 2a 20 74 6f 20 62 65 20 70 d not.** to be p
3d040 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 inned..**.** Whe
3d050 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 n SQLite calls t
3d060 68 65 20 78 54 72 75 6e 63 61 74 65 28 29 20 6d he xTruncate() m
3d070 65 74 68 6f 64 2c 20 74 68 65 20 63 61 63 68 65 ethod, the cache
3d080 20 6d 75 73 74 20 64 69 73 63 61 72 64 20 61 6c must discard al
3d090 6c 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 63 61 l.** existing ca
3d0a0 63 68 65 20 65 6e 74 72 69 65 73 20 77 69 74 68 che entries with
3d0b0 20 70 61 67 65 20 6e 75 6d 62 65 72 73 20 28 6b page numbers (k
3d0c0 65 79 73 29 20 67 72 65 61 74 65 72 20 74 68 61 eys) greater tha
3d0d0 6e 20 6f 72 20 65 71 75 61 6c 0a 2a 2a 20 74 6f n or equal.** to
3d0e0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
3d0f0 65 20 69 4c 69 6d 69 74 20 70 61 72 61 6d 65 74 e iLimit paramet
3d100 65 72 20 70 61 73 73 65 64 20 74 6f 20 78 54 72 er passed to xTr
3d110 75 6e 63 61 74 65 28 29 2e 20 49 66 20 61 6e 79 uncate(). If any
3d120 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 70 61 67 .** of these pag
3d130 65 73 20 61 72 65 20 70 69 6e 6e 65 64 2c 20 74 es are pinned, t
3d140 68 65 79 20 61 72 65 20 69 6d 70 6c 69 63 69 74 hey are implicit
3d150 6c 79 20 75 6e 70 69 6e 6e 65 64 2c 20 6d 65 61 ly unpinned, mea
3d160 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 74 68 65 ning that.** the
3d170 79 20 63 61 6e 20 62 65 20 73 61 66 65 6c 79 20 y can be safely
3d180 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 0a 2a 2a discarded..**.**
3d190 20 54 68 65 20 78 44 65 73 74 72 6f 79 28 29 20 The xDestroy()
3d1a0 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 method is used t
3d1b0 6f 20 64 65 6c 65 74 65 20 61 20 63 61 63 68 65 o delete a cache
3d1c0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 78 43 allocated by xC
3d1d0 72 65 61 74 65 28 29 2e 0a 2a 2a 20 41 6c 6c 20 reate()..** All
3d1e0 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69 resources associ
3d1f0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 70 ated with the sp
3d200 65 63 69 66 69 65 64 20 63 61 63 68 65 20 73 68 ecified cache sh
3d210 6f 75 6c 64 20 62 65 20 66 72 65 65 64 2e 20 41 ould be freed. A
3d220 66 74 65 72 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 fter.** calling
3d230 74 68 65 20 78 44 65 73 74 72 6f 79 28 29 20 6d the xDestroy() m
3d240 65 74 68 6f 64 2c 20 53 51 4c 69 74 65 20 63 6f ethod, SQLite co
3d250 6e 73 69 64 65 72 73 20 74 68 65 20 5b 73 71 6c nsiders the [sql
3d260 69 74 65 33 5f 70 63 61 63 68 65 2a 5d 0a 2a 2a ite3_pcache*].**
3d270 20 68 61 6e 64 6c 65 20 69 6e 76 61 6c 69 64 2c handle invalid,
3d280 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 75 73 and will not us
3d290 65 20 69 74 20 77 69 74 68 20 61 6e 79 20 6f 74 e it with any ot
3d2a0 68 65 72 20 73 71 6c 69 74 65 33 5f 70 63 61 63 her sqlite3_pcac
3d2b0 68 65 5f 6d 65 74 68 6f 64 73 0a 2a 2a 20 66 75 he_methods.** fu
3d2c0 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 nctions..*/.type
3d2d0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
3d2e0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
3d2f0 73 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 s sqlite3_pcache
3d300 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
3d310 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
3d320 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 methods {. void
3d330 20 2a 70 41 72 67 3b 0a 20 20 69 6e 74 20 28 2a *pArg;. int (*
3d340 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 0a 20 xInit)(void*);.
3d350 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 void (*xShutdow
3d360 6e 29 28 76 6f 69 64 2a 29 3b 0a 20 20 73 71 6c n)(void*);. sql
3d370 69 74 65 33 5f 70 63 61 63 68 65 20 2a 28 2a 78 ite3_pcache *(*x
3d380 43 72 65 61 74 65 29 28 69 6e 74 20 73 7a 50 61 Create)(int szPa
3d390 67 65 2c 20 69 6e 74 20 62 50 75 72 67 65 61 62 ge, int bPurgeab
3d3a0 6c 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 43 le);. void (*xC
3d3b0 61 63 68 65 73 69 7a 65 29 28 73 71 6c 69 74 65 achesize)(sqlite
3d3c0 33 5f 70 63 61 63 68 65 2a 2c 20 69 6e 74 20 6e 3_pcache*, int n
3d3d0 43 61 63 68 65 73 69 7a 65 29 3b 0a 20 20 69 6e Cachesize);. in
3d3e0 74 20 28 2a 78 50 61 67 65 63 6f 75 6e 74 29 28 t (*xPagecount)(
3d3f0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 29 sqlite3_pcache*)
3d400 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 46 65 74 ;. void *(*xFet
3d410 63 68 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 ch)(sqlite3_pcac
3d420 68 65 2a 2c 20 75 6e 73 69 67 6e 65 64 20 6b 65 he*, unsigned ke
3d430 79 2c 20 69 6e 74 20 63 72 65 61 74 65 46 6c 61 y, int createFla
3d440 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 55 6e g);. void (*xUn
3d450 70 69 6e 29 28 73 71 6c 69 74 65 33 5f 70 63 61 pin)(sqlite3_pca
3d460 63 68 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 che*, void*, int
3d470 20 64 69 73 63 61 72 64 29 3b 0a 20 20 76 6f 69 discard);. voi
3d480 64 20 28 2a 78 52 65 6b 65 79 29 28 73 71 6c 69 d (*xRekey)(sqli
3d490 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 6f 69 te3_pcache*, voi
3d4a0 64 2a 2c 20 75 6e 73 69 67 6e 65 64 20 6f 6c 64 d*, unsigned old
3d4b0 4b 65 79 2c 20 75 6e 73 69 67 6e 65 64 20 6e 65 Key, unsigned ne
3d4c0 77 4b 65 79 29 3b 0a 20 20 76 6f 69 64 20 28 2a wKey);. void (*
3d4d0 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 xTruncate)(sqlit
3d4e0 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e 73 69 e3_pcache*, unsi
3d4f0 67 6e 65 64 20 69 4c 69 6d 69 74 29 3b 0a 20 20 gned iLimit);.
3d500 76 6f 69 64 20 28 2a 78 44 65 73 74 72 6f 79 29 void (*xDestroy)
3d510 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a (sqlite3_pcache*
3d520 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 );.};../*.** CAP
3d530 49 33 52 45 46 3a 20 4f 6e 6c 69 6e 65 20 42 61 I3REF: Online Ba
3d540 63 6b 75 70 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 ckup Object.** E
3d550 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
3d560 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 61 * The sqlite3_ba
3d570 63 6b 75 70 20 6f 62 6a 65 63 74 20 72 65 63 6f ckup object reco
3d580 72 64 73 20 73 74 61 74 65 20 69 6e 66 6f 72 6d rds state inform
3d590 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 6e 20 6f ation about an o
3d5a0 6e 67 6f 69 6e 67 0a 2a 2a 20 6f 6e 6c 69 6e 65 ngoing.** online
3d5b0 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f backup operatio
3d5c0 6e 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f n. The sqlite3_
3d5d0 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 20 69 73 backup object is
3d5e0 20 63 72 65 61 74 65 64 20 62 79 0a 2a 2a 20 61 created by.** a
3d5f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
3d600 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 5d 3_backup_init()]
3d610 20 61 6e 64 20 69 73 20 64 65 73 74 72 6f 79 65 and is destroye
3d620 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 0a 2a d by a call to.*
3d630 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 * [sqlite3_backu
3d640 70 5f 66 69 6e 69 73 68 28 29 5d 2e 0a 2a 2a 0a p_finish()]..**.
3d650 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 5b 55 73 ** See Also: [Us
3d660 69 6e 67 20 74 68 65 20 53 51 4c 69 74 65 20 4f ing the SQLite O
3d670 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 41 50 49 nline Backup API
3d680 5d 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ].*/.typedef str
3d690 75 63 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b uct sqlite3_back
3d6a0 75 70 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 up sqlite3_backu
3d6b0 70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 p;../*.** CAPI3R
3d6c0 45 46 3a 20 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 EF: Online Backu
3d6d0 70 20 41 50 49 2e 0a 2a 2a 20 45 58 50 45 52 49 p API..** EXPERI
3d6e0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 MENTAL.**.** Thi
3d6f0 73 20 41 50 49 20 69 73 20 75 73 65 64 20 74 6f s API is used to
3d700 20 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 overwrite the c
3d710 6f 6e 74 65 6e 74 73 20 6f 66 20 6f 6e 65 20 64 ontents of one d
3d720 61 74 61 62 61 73 65 20 77 69 74 68 20 74 68 61 atabase with tha
3d730 74 0a 2a 2a 20 6f 66 20 61 6e 6f 74 68 65 72 2e t.** of another.
3d740 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 65 69 It is useful ei
3d750 74 68 65 72 20 66 6f 72 20 63 72 65 61 74 69 6e ther for creatin
3d760 67 20 62 61 63 6b 75 70 73 20 6f 66 20 64 61 74 g backups of dat
3d770 61 62 61 73 65 73 20 6f 72 0a 2a 2a 20 66 6f 72 abases or.** for
3d780 20 63 6f 70 79 69 6e 67 20 69 6e 2d 6d 65 6d 6f copying in-memo
3d790 72 79 20 64 61 74 61 62 61 73 65 73 20 74 6f 20 ry databases to
3d7a0 6f 72 20 66 72 6f 6d 20 70 65 72 73 69 73 74 65 or from persiste
3d7b0 6e 74 20 66 69 6c 65 73 2e 20 0a 2a 2a 0a 2a 2a nt files. .**.**
3d7c0 20 53 65 65 20 41 6c 73 6f 3a 20 5b 55 73 69 6e See Also: [Usin
3d7d0 67 20 74 68 65 20 53 51 4c 69 74 65 20 4f 6e 6c g the SQLite Onl
3d7e0 69 6e 65 20 42 61 63 6b 75 70 20 41 50 49 5d 0a ine Backup API].
3d7f0 2a 2a 0a 2a 2a 20 45 78 63 6c 75 73 69 76 65 20 **.** Exclusive
3d800 61 63 63 65 73 73 20 69 73 20 72 65 71 75 69 72 access is requir
3d810 65 64 20 74 6f 20 74 68 65 20 64 65 73 74 69 6e ed to the destin
3d820 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 66 ation database f
3d830 6f 72 20 74 68 65 20 0a 2a 2a 20 64 75 72 61 74 or the .** durat
3d840 69 6f 6e 20 6f 66 20 74 68 65 20 6f 70 65 72 61 ion of the opera
3d850 74 69 6f 6e 2e 20 48 6f 77 65 76 65 72 20 74 68 tion. However th
3d860 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 e source databas
3d870 65 20 69 73 20 6f 6e 6c 79 0a 2a 2a 20 72 65 61 e is only.** rea
3d880 64 2d 6c 6f 63 6b 65 64 20 77 68 69 6c 65 20 69 d-locked while i
3d890 74 20 69 73 20 61 63 74 75 61 6c 6c 79 20 62 65 t is actually be
3d8a0 69 6e 67 20 72 65 61 64 2c 20 69 74 20 69 73 20 ing read, it is
3d8b0 6e 6f 74 20 6c 6f 63 6b 65 64 0a 2a 2a 20 63 6f not locked.** co
3d8c0 6e 74 69 6e 75 6f 75 73 6c 79 20 66 6f 72 20 74 ntinuously for t
3d8d0 68 65 20 65 6e 74 69 72 65 20 6f 70 65 72 61 74 he entire operat
3d8e0 69 6f 6e 2e 20 54 68 75 73 2c 20 74 68 65 20 62 ion. Thus, the b
3d8f0 61 63 6b 75 70 20 6d 61 79 20 62 65 0a 2a 2a 20 ackup may be.**
3d900 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 61 20 6c performed on a l
3d910 69 76 65 20 64 61 74 61 62 61 73 65 20 77 69 74 ive database wit
3d920 68 6f 75 74 20 70 72 65 76 65 6e 74 69 6e 67 20 hout preventing
3d930 6f 74 68 65 72 20 75 73 65 72 73 20 66 72 6f 6d other users from
3d940 0a 2a 2a 20 77 72 69 74 69 6e 67 20 74 6f 20 74 .** writing to t
3d950 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 he database for
3d960 61 6e 20 65 78 74 65 6e 64 65 64 20 70 65 72 69 an extended peri
3d970 6f 64 20 6f 66 20 74 69 6d 65 2e 0a 2a 2a 20 0a od of time..** .
3d980 2a 2a 20 54 6f 20 70 65 72 66 6f 72 6d 20 61 20 ** To perform a
3d990 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e backup operation
3d9a0 3a 20 0a 2a 2a 20 20 20 3c 6f 6c 3e 0a 2a 2a 20 : .** <ol>.**
3d9b0 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 <li><b>sqlit
3d9c0 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 e3_backup_init()
3d9d0 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 20 6f </b> is called o
3d9e0 6e 63 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a nce to initializ
3d9f0 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 e the.**
3da00 20 62 61 63 6b 75 70 2c 20 0a 2a 2a 20 20 20 20 backup, .**
3da10 20 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 33 5f <li><b>sqlite3_
3da20 62 61 63 6b 75 70 5f 73 74 65 70 28 29 3c 2f 62 backup_step()</b
3da30 3e 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 > is called one
3da40 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f or more times to
3da50 20 74 72 61 6e 73 66 65 72 20 0a 2a 2a 20 20 20 transfer .**
3da60 20 20 20 20 20 20 74 68 65 20 64 61 74 61 20 62 the data b
3da70 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 64 etween the two d
3da80 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 66 69 atabases, and fi
3da90 6e 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 3c 6c 69 nally.** <li
3daa0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b ><b>sqlite3_back
3dab0 75 70 5f 66 69 6e 69 73 68 28 29 3c 2f 62 3e 20 up_finish()</b>
3dac0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 6c is called to rel
3dad0 65 61 73 65 20 61 6c 6c 20 72 65 73 6f 75 72 63 ease all resourc
3dae0 65 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 61 es .** a
3daf0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
3db00 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 he backup operat
3db10 69 6f 6e 2e 20 0a 2a 2a 20 20 20 3c 2f 6f 6c 3e ion. .** </ol>
3db20 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
3db30 20 62 65 20 65 78 61 63 74 6c 79 20 6f 6e 65 20 be exactly one
3db40 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
3db50 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 20 backup_finish()
3db60 66 6f 72 20 65 61 63 68 0a 2a 2a 20 73 75 63 63 for each.** succ
3db70 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 73 essful call to s
3db80 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e qlite3_backup_in
3db90 69 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 it()..**.** <b>s
3dba0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e qlite3_backup_in
3dbb0 69 74 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 it()</b>.**.** T
3dbc0 68 65 20 66 69 72 73 74 20 74 77 6f 20 61 72 67 he first two arg
3dbd0 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20 74 6f uments passed to
3dbe0 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 [sqlite3_backup
3dbf0 5f 69 6e 69 74 28 29 5d 20 61 72 65 20 74 68 65 _init()] are the
3dc00 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e database.** han
3dc10 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 dle associated w
3dc20 69 74 68 20 74 68 65 20 64 65 73 74 69 6e 61 74 ith the destinat
3dc30 69 6f 6e 20 64 61 74 61 62 61 73 65 20 61 6e 64 ion database and
3dc40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
3dc50 6d 65 20 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 me .** used to a
3dc60 74 74 61 63 68 20 74 68 65 20 64 65 73 74 69 6e ttach the destin
3dc70 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 74 ation database t
3dc80 6f 20 74 68 65 20 68 61 6e 64 6c 65 2e 20 54 68 o the handle. Th
3dc90 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 0a e database name.
3dca0 2a 2a 20 69 73 20 22 6d 61 69 6e 22 20 66 6f 72 ** is "main" for
3dcb0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 the main databa
3dcc0 73 65 2c 20 22 74 65 6d 70 22 20 66 6f 72 20 74 se, "temp" for t
3dcd0 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 61 74 he temporary dat
3dce0 61 62 61 73 65 2c 20 6f 72 0a 2a 2a 20 74 68 65 abase, or.** the
3dcf0 20 6e 61 6d 65 20 73 70 65 63 69 66 69 65 64 20 name specified
3dd00 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 5b as part of the [
3dd10 41 54 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e ATTACH] statemen
3dd20 74 20 69 66 20 74 68 65 20 64 65 73 74 69 6e 61 t if the destina
3dd30 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 6e 20 61 74 tion is.** an at
3dd40 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2e tached database.
3dd50 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 The third and f
3dd60 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 ourth arguments
3dd70 70 61 73 73 65 64 20 74 6f 20 0a 2a 2a 20 73 71 passed to .** sq
3dd80 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 lite3_backup_ini
3dd90 74 28 29 20 69 64 65 6e 74 69 66 79 20 74 68 65 t() identify the
3dda0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
3ddb0 63 74 69 6f 6e 5d 0a 2a 2a 20 61 6e 64 20 64 61 ction].** and da
3ddc0 74 61 62 61 73 65 20 6e 61 6d 65 20 75 73 65 64 tabase name used
3ddd0 0a 2a 2a 20 74 6f 20 61 63 63 65 73 73 20 74 68 .** to access th
3dde0 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 e source databas
3ddf0 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 70 61 e. The values pa
3de00 73 73 65 64 20 66 6f 72 20 74 68 65 20 73 6f 75 ssed for the sou
3de10 72 63 65 20 61 6e 64 20 0a 2a 2a 20 64 65 73 74 rce and .** dest
3de20 69 6e 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 73 ination [databas
3de30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 e connection] pa
3de40 72 61 6d 65 74 65 72 73 20 6d 75 73 74 20 6e 6f rameters must no
3de50 74 20 62 65 20 74 68 65 20 73 61 6d 65 2e 0a 2a t be the same..*
3de60 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 *.** If an error
3de70 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 73 occurs within s
3de80 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e qlite3_backup_in
3de90 69 74 28 29 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 it(), then NULL
3dea0 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 61 is returned.** a
3deb0 6e 64 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 nd an error code
3dec0 20 61 6e 64 20 65 72 72 6f 72 20 6d 65 73 73 61 and error messa
3ded0 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ge written into
3dee0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
3def0 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a 20 70 61 nnection] .** pa
3df00 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 ssed as the firs
3df10 74 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 79 t argument. They
3df20 20 6d 61 79 20 62 65 20 72 65 74 72 69 65 76 65 may be retrieve
3df30 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b d using the.** [
3df40 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
3df50 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 )], [sqlite3_err
3df60 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c msg()], and [sql
3df70 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d ite3_errmsg16()]
3df80 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 4f functions..** O
3df90 74 68 65 72 77 69 73 65 2c 20 69 66 20 73 75 63 therwise, if suc
3dfa0 63 65 73 73 66 75 6c 2c 20 61 20 70 6f 69 6e 74 cessful, a point
3dfb0 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 er to an [sqlite
3dfc0 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 3_backup] object
3dfd0 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 2e is.** returned.
3dfe0 20 54 68 69 73 20 70 6f 69 6e 74 65 72 20 6d 61 This pointer ma
3dff0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 y be used with t
3e000 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 he sqlite3_backu
3e010 70 5f 73 74 65 70 28 29 20 61 6e 64 0a 2a 2a 20 p_step() and.**
3e020 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 sqlite3_backup_f
3e030 69 6e 69 73 68 28 29 20 66 75 6e 63 74 69 6f 6e inish() function
3e040 73 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 s to perform the
3e050 20 73 70 65 63 69 66 69 65 64 20 62 61 63 6b 75 specified backu
3e060 70 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 2e p .** operation.
3e070 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 .**.** <b>sqlite
3e080 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 3c 3_backup_step()<
3e090 2f 62 3e 0a 2a 2a 0a 2a 2a 20 46 75 6e 63 74 69 /b>.**.** Functi
3e0a0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b on [sqlite3_back
3e0b0 75 70 5f 73 74 65 70 28 29 5d 20 69 73 20 75 73 up_step()] is us
3e0c0 65 64 20 74 6f 20 63 6f 70 79 20 75 70 20 74 6f ed to copy up to
3e0d0 20 6e 50 61 67 65 20 70 61 67 65 73 20 62 65 74 nPage pages bet
3e0e0 77 65 65 6e 20 0a 2a 2a 20 74 68 65 20 73 6f 75 ween .** the sou
3e0f0 72 63 65 20 61 6e 64 20 64 65 73 74 69 6e 61 74 rce and destinat
3e100 69 6f 6e 20 64 61 74 61 62 61 73 65 73 2c 20 77 ion databases, w
3e110 68 65 72 65 20 6e 50 61 67 65 20 69 73 20 74 68 here nPage is th
3e120 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 0a e value of the .
3e130 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
3e140 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 73 71 ter passed to sq
3e150 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3e160 70 28 29 2e 20 49 66 20 6e 50 61 67 65 20 69 73 p(). If nPage is
3e170 20 61 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 a negative.** v
3e180 61 6c 75 65 2c 20 61 6c 6c 20 72 65 6d 61 69 6e alue, all remain
3e190 69 6e 67 20 73 6f 75 72 63 65 20 70 61 67 65 73 ing source pages
3e1a0 20 61 72 65 20 63 6f 70 69 65 64 2e 20 49 66 20 are copied. If
3e1b0 74 68 65 20 72 65 71 75 69 72 65 64 20 70 61 67 the required pag
3e1c0 65 73 20 61 72 65 20 0a 2a 2a 20 73 75 63 63 65 es are .** succe
3e1d0 73 66 75 6c 6c 79 20 63 6f 70 69 65 64 2c 20 62 sfully copied, b
3e1e0 75 74 20 74 68 65 72 65 20 61 72 65 20 73 74 69 ut there are sti
3e1f0 6c 6c 20 6d 6f 72 65 20 70 61 67 65 73 20 74 6f ll more pages to
3e200 20 63 6f 70 79 20 62 65 66 6f 72 65 20 74 68 65 copy before the
3e210 20 0a 2a 2a 20 62 61 63 6b 75 70 20 69 73 20 63 .** backup is c
3e220 6f 6d 70 6c 65 74 65 2c 20 69 74 20 72 65 74 75 omplete, it retu
3e230 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e rns [SQLITE_OK].
3e240 20 49 66 20 6e 6f 20 65 72 72 6f 72 20 6f 63 63 If no error occ
3e250 75 72 65 64 20 61 6e 64 20 74 68 65 72 65 20 0a ured and there .
3e260 2a 2a 20 61 72 65 20 6e 6f 20 6d 6f 72 65 20 70 ** are no more p
3e270 61 67 65 73 20 74 6f 20 63 6f 70 79 2c 20 74 68 ages to copy, th
3e280 65 6e 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d en [SQLITE_DONE]
3e290 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 is returned. If
3e2a0 20 61 6e 20 65 72 72 6f 72 20 0a 2a 2a 20 6f 63 an error .** oc
3e2b0 63 75 72 73 2c 20 74 68 65 6e 20 61 6e 20 53 51 curs, then an SQ
3e2c0 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 Lite error code
3e2d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 41 73 20 is returned. As
3e2e0 77 65 6c 6c 20 61 73 20 5b 53 51 4c 49 54 45 5f well as [SQLITE_
3e2f0 4f 4b 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 OK] and.** [SQLI
3e300 54 45 5f 44 4f 4e 45 5d 2c 20 61 20 63 61 6c 6c TE_DONE], a call
3e310 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3e320 75 70 5f 73 74 65 70 28 29 20 6d 61 79 20 72 65 up_step() may re
3e330 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 turn [SQLITE_REA
3e340 44 4f 4e 4c 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 DONLY],.** [SQLI
3e350 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 TE_NOMEM], [SQLI
3e360 54 45 5f 42 55 53 59 5d 2c 20 5b 53 51 4c 49 54 TE_BUSY], [SQLIT
3e370 45 5f 4c 4f 43 4b 45 44 5d 2c 20 6f 72 20 61 6e E_LOCKED], or an
3e380 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 .** [SQLITE_IOER
3e390 52 5f 41 43 43 45 53 53 20 7c 20 53 51 4c 49 54 R_ACCESS | SQLIT
3e3a0 45 5f 49 4f 45 52 52 5f 58 58 58 5d 20 65 78 74 E_IOERR_XXX] ext
3e3b0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
3e3c0 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 ..**.** As well
3e3d0 61 73 20 74 68 65 20 63 61 73 65 20 77 68 65 72 as the case wher
3e3e0 65 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f e the destinatio
3e3f0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 n database file
3e400 77 61 73 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a was opened for.*
3e410 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 * read-only acce
3e420 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 61 63 6b ss, sqlite3_back
3e430 75 70 5f 73 74 65 70 28 29 20 6d 61 79 20 72 65 up_step() may re
3e440 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 turn [SQLITE_REA
3e450 44 4f 4e 4c 59 5d 20 69 66 0a 2a 2a 20 74 68 65 DONLY] if.** the
3e460 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 69 73 20 destination is
3e470 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 an in-memory dat
3e480 61 62 61 73 65 20 77 69 74 68 20 61 20 64 69 66 abase with a dif
3e490 66 65 72 65 6e 74 20 70 61 67 65 20 73 69 7a 65 ferent page size
3e4a0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 6f 75 .** from the sou
3e4b0 72 63 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a rce database..**
3e4c0 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 62 .** If sqlite3_b
3e4d0 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 61 6e ackup_step() can
3e4e0 6e 6f 74 20 6f 62 74 61 69 6e 20 61 20 72 65 71 not obtain a req
3e4f0 75 69 72 65 64 20 66 69 6c 65 2d 73 79 73 74 65 uired file-syste
3e500 6d 20 6c 6f 63 6b 2c 20 74 68 65 6e 0a 2a 2a 20 m lock, then.**
3e510 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 the [sqlite3_bus
3e520 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 y_handler | busy
3e530 2d 68 61 6e 64 6c 65 72 20 66 75 6e 63 74 69 6f -handler functio
3e540 6e 5d 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 n].** is invoked
3e550 20 28 69 66 20 6f 6e 65 20 69 73 20 73 70 65 63 (if one is spec
3e560 69 66 69 65 64 29 2e 20 49 66 20 74 68 65 20 0a ified). If the .
3e570 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 ** busy-handler
3e580 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
3e590 20 62 65 66 6f 72 65 20 74 68 65 20 6c 6f 63 6b before the lock
3e5a0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2c 20 74 is available, t
3e5b0 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f hen .** [SQLITE_
3e5c0 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 BUSY] is returne
3e5d0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e d to the caller.
3e5e0 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 In this case th
3e5f0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c e call to.** sql
3e600 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3e610 28 29 20 63 61 6e 20 62 65 20 72 65 74 72 69 65 () can be retrie
3e620 64 20 6c 61 74 65 72 2e 20 49 66 20 74 68 65 20 d later. If the
3e630 73 6f 75 72 63 65 0a 2a 2a 20 5b 64 61 74 61 62 source.** [datab
3e640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
3e650 2a 2a 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 ** is being used
3e660 20 74 6f 20 77 72 69 74 65 20 74 6f 20 74 68 65 to write to the
3e670 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 source database
3e680 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 62 61 when sqlite3_ba
3e690 63 6b 75 70 5f 73 74 65 70 28 29 0a 2a 2a 20 69 ckup_step().** i
3e6a0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 5b s called, then [
3e6b0 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 69 SQLITE_LOCKED] i
3e6c0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
3e6d0 69 61 74 65 6c 79 2e 20 41 67 61 69 6e 2c 20 69 iately. Again, i
3e6e0 6e 20 74 68 69 73 0a 2a 2a 20 63 61 73 65 20 74 n this.** case t
3e6f0 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 he call to sqlit
3e700 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3e710 20 63 61 6e 20 62 65 20 72 65 74 72 69 65 64 20 can be retried
3e720 6c 61 74 65 72 20 6f 6e 2e 20 49 66 0a 2a 2a 20 later on. If.**
3e730 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 [SQLITE_IOERR_AC
3e740 43 45 53 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f CESS | SQLITE_IO
3e750 45 52 52 5f 58 58 58 5d 2c 20 5b 53 51 4c 49 54 ERR_XXX], [SQLIT
3e760 45 5f 4e 4f 4d 45 4d 5d 2c 20 6f 72 0a 2a 2a 20 E_NOMEM], or.**
3e770 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 [SQLITE_READONLY
3e780 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 74 ] is returned, t
3e790 68 65 6e 20 0a 2a 2a 20 74 68 65 72 65 20 69 73 hen .** there is
3e7a0 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 72 65 74 no point in ret
3e7b0 72 79 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74 rying the call t
3e7c0 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
3e7d0 5f 73 74 65 70 28 29 2e 20 54 68 65 73 65 20 0a _step(). These .
3e7e0 2a 2a 20 65 72 72 6f 72 73 20 61 72 65 20 63 6f ** errors are co
3e7f0 6e 73 69 64 65 72 65 64 20 66 61 74 61 6c 2e 20 nsidered fatal.
3e800 41 74 20 74 68 69 73 20 70 6f 69 6e 74 20 74 68 At this point th
3e810 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
3e820 73 74 20 61 63 63 65 70 74 20 0a 2a 2a 20 74 68 st accept .** th
3e830 61 74 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 at the backup op
3e840 65 72 61 74 69 6f 6e 20 68 61 73 20 66 61 69 6c eration has fail
3e850 65 64 20 61 6e 64 20 70 61 73 73 20 74 68 65 20 ed and pass the
3e860 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e backup operation
3e870 20 68 61 6e 64 6c 65 20 0a 2a 2a 20 74 6f 20 74 handle .** to t
3e880 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 he sqlite3_backu
3e890 70 5f 66 69 6e 69 73 68 28 29 20 74 6f 20 72 65 p_finish() to re
3e8a0 6c 65 61 73 65 20 61 73 73 6f 63 69 61 74 65 64 lease associated
3e8b0 20 72 65 73 6f 75 72 63 65 73 2e 0a 2a 2a 0a 2a resources..**.*
3e8c0 2a 20 46 6f 6c 6c 6f 77 69 6e 67 20 74 68 65 20 * Following the
3e8d0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 73 71 first call to sq
3e8e0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3e8f0 70 28 29 2c 20 61 6e 20 65 78 63 6c 75 73 69 76 p(), an exclusiv
3e900 65 20 6c 6f 63 6b 20 69 73 0a 2a 2a 20 6f 62 74 e lock is.** obt
3e910 61 69 6e 65 64 20 6f 6e 20 74 68 65 20 64 65 73 ained on the des
3e920 74 69 6e 61 74 69 6f 6e 20 66 69 6c 65 2e 20 49 tination file. I
3e930 74 20 69 73 20 6e 6f 74 20 72 65 6c 65 61 73 65 t is not release
3e940 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 0a d until either .
3e950 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ** sqlite3_backu
3e960 70 5f 66 69 6e 69 73 68 28 29 20 69 73 20 63 61 p_finish() is ca
3e970 6c 6c 65 64 20 6f 72 20 74 68 65 20 62 61 63 6b lled or the back
3e980 75 70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 up operation is
3e990 63 6f 6d 70 6c 65 74 65 20 0a 2a 2a 20 61 6e 64 complete .** and
3e9a0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3e9b0 73 74 65 70 28 29 20 72 65 74 75 72 6e 73 20 5b step() returns [
3e9c0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 41 64 SQLITE_DONE]. Ad
3e9d0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 65 61 63 68 ditionally, each
3e9e0 20 74 69 6d 65 20 0a 2a 2a 20 61 20 63 61 6c 6c time .** a call
3e9f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3ea00 75 70 5f 73 74 65 70 28 29 20 69 73 20 6d 61 64 up_step() is mad
3ea10 65 20 61 20 5b 73 68 61 72 65 64 20 6c 6f 63 6b e a [shared lock
3ea20 5d 20 69 73 20 6f 62 74 61 69 6e 65 64 20 6f 6e ] is obtained on
3ea30 0a 2a 2a 20 74 68 65 20 73 6f 75 72 63 65 20 64 .** the source d
3ea40 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 54 68 atabase file. Th
3ea50 69 73 20 6c 6f 63 6b 20 69 73 20 72 65 6c 65 61 is lock is relea
3ea60 73 65 64 20 62 65 66 6f 72 65 20 74 68 65 0a 2a sed before the.*
3ea70 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 * sqlite3_backup
3ea80 5f 73 74 65 70 28 29 20 63 61 6c 6c 20 72 65 74 _step() call ret
3ea90 75 72 6e 73 2e 20 42 65 63 61 75 73 65 20 74 68 urns. Because th
3eaa0 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 e source databas
3eab0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 6c 6f 63 6b e is not.** lock
3eac0 65 64 20 62 65 74 77 65 65 6e 20 63 61 6c 6c 73 ed between calls
3ead0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3eae0 75 70 5f 73 74 65 70 28 29 2c 20 69 74 20 6d 61 up_step(), it ma
3eaf0 79 20 62 65 20 6d 6f 64 69 66 69 65 64 20 6d 69 y be modified mi
3eb00 64 2d 77 61 79 0a 2a 2a 20 74 68 72 6f 75 67 68 d-way.** through
3eb10 20 74 68 65 20 62 61 63 6b 75 70 20 70 72 6f 63 the backup proc
3eb20 65 64 75 72 65 2e 20 49 66 20 74 68 65 20 73 6f edure. If the so
3eb30 75 72 63 65 20 64 61 74 61 62 61 73 65 20 69 73 urce database is
3eb40 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a modified by an.
3eb50 2a 2a 20 65 78 74 65 72 6e 61 6c 20 70 72 6f 63 ** external proc
3eb60 65 73 73 20 6f 72 20 76 69 61 20 61 20 64 61 74 ess or via a dat
3eb70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3eb80 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 other than the
3eb90 6f 6e 65 20 62 65 69 6e 67 0a 2a 2a 20 75 73 65 one being.** use
3eba0 64 20 62 79 20 74 68 65 20 62 61 63 6b 75 70 20 d by the backup
3ebb0 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 6e 20 operation, then
3ebc0 74 68 65 20 62 61 63 6b 75 70 20 77 69 6c 6c 20 the backup will
3ebd0 62 65 20 74 72 61 6e 73 70 61 72 65 6e 74 6c 79 be transparently
3ebe0 0a 2a 2a 20 72 65 73 74 61 72 74 65 64 20 62 79 .** restarted by
3ebf0 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 the next call t
3ec00 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
3ec10 5f 73 74 65 70 28 29 2e 20 49 66 20 74 68 65 20 _step(). If the
3ec20 73 6f 75 72 63 65 20 0a 2a 2a 20 64 61 74 61 62 source .** datab
3ec30 61 73 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 ase is modified
3ec40 62 79 20 74 68 65 20 75 73 69 6e 67 20 74 68 65 by the using the
3ec50 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
3ec60 6f 6e 6e 65 63 74 69 6f 6e 20 61 73 20 69 73 20 onnection as is
3ec70 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 62 used.** by the b
3ec80 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2c ackup operation,
3ec90 20 74 68 65 6e 20 74 68 65 20 62 61 63 6b 75 70 then the backup
3eca0 20 64 61 74 61 62 61 73 65 20 69 73 20 74 72 61 database is tra
3ecb0 6e 73 70 61 72 65 6e 74 6c 79 20 0a 2a 2a 20 75 nsparently .** u
3ecc0 70 64 61 74 65 64 20 61 74 20 74 68 65 20 73 61 pdated at the sa
3ecd0 6d 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c me time..**.** <
3ece0 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 b>sqlite3_backup
3ecf0 5f 66 69 6e 69 73 68 28 29 3c 2f 62 3e 0a 2a 2a _finish()</b>.**
3ed00 0a 2a 2a 20 4f 6e 63 65 20 73 71 6c 69 74 65 33 .** Once sqlite3
3ed10 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 68 _backup_step() h
3ed20 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c as returned [SQL
3ed30 49 54 45 5f 44 4f 4e 45 5d 2c 20 6f 72 20 77 68 ITE_DONE], or wh
3ed40 65 6e 20 74 68 65 20 0a 2a 2a 20 61 70 70 6c 69 en the .** appli
3ed50 63 61 74 69 6f 6e 20 77 69 73 68 65 73 20 74 6f cation wishes to
3ed60 20 61 62 61 6e 64 6f 6e 20 74 68 65 20 62 61 63 abandon the bac
3ed70 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 kup operation, t
3ed80 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b he [sqlite3_back
3ed90 75 70 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 73 68 up].** object sh
3eda0 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 74 ould be passed t
3edb0 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
3edc0 5f 66 69 6e 69 73 68 28 29 2e 20 54 68 69 73 20 _finish(). This
3edd0 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 releases all.**
3ede0 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69 resources associ
3edf0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 62 61 ated with the ba
3ee00 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 ckup operation.
3ee10 49 66 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 If sqlite3_backu
3ee20 70 5f 73 74 65 70 28 29 0a 2a 2a 20 68 61 73 20 p_step().** has
3ee30 6e 6f 74 20 79 65 74 20 72 65 74 75 72 6e 65 64 not yet returned
3ee40 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 [SQLITE_DONE],
3ee50 74 68 65 6e 20 61 6e 79 20 61 63 74 69 76 65 20 then any active
3ee60 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74 69 6f write-transactio
3ee70 6e 20 6f 6e 20 74 68 65 0a 2a 2a 20 64 65 73 74 n on the.** dest
3ee80 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 ination database
3ee90 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e is rolled back.
3eea0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 The [sqlite3_ba
3eeb0 63 6b 75 70 5d 20 6f 62 6a 65 63 74 20 69 73 20 ckup] object is
3eec0 69 6e 76 61 6c 69 64 0a 2a 2a 20 61 6e 64 20 6d invalid.** and m
3eed0 61 79 20 6e 6f 74 20 62 65 20 75 73 65 64 20 66 ay not be used f
3eee0 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 ollowing a call
3eef0 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3ef00 70 5f 66 69 6e 69 73 68 28 29 2e 0a 2a 2a 0a 2a p_finish()..**.*
3ef10 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 * The value retu
3ef20 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
3ef30 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 69 73 backup_finish is
3ef40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 [SQLITE_OK] if
3ef50 6e 6f 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 no error.** occu
3ef60 72 72 65 64 2c 20 72 65 67 61 72 64 6c 65 73 73 rred, regardless
3ef70 20 6f 72 20 77 68 65 74 68 65 72 20 6f 72 20 6e or whether or n
3ef80 6f 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ot sqlite3_backu
3ef90 70 5f 73 74 65 70 28 29 20 77 61 73 20 63 61 6c p_step() was cal
3efa0 6c 65 64 0a 2a 2a 20 61 20 73 75 66 66 69 63 69 led.** a suffici
3efb0 65 6e 74 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 ent number of ti
3efc0 6d 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 65 20 mes to complete
3efd0 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 the backup opera
3efe0 74 69 6f 6e 2e 20 4f 72 2c 20 69 66 0a 2a 2a 20 tion. Or, if.**
3eff0 61 6e 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 an out-of-memory
3f000 20 63 6f 6e 64 69 74 69 6f 6e 20 6f 72 20 49 4f condition or IO
3f010 20 65 72 72 6f 72 20 6f 63 63 75 72 65 64 20 64 error occured d
3f020 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a uring a call to.
3f030 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ** sqlite3_backu
3f040 70 5f 73 74 65 70 28 29 20 74 68 65 6e 20 5b 53 p_step() then [S
3f050 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 6f 72 20 QLITE_NOMEM] or
3f060 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f an.** [SQLITE_IO
3f070 45 52 52 5f 41 43 43 45 53 53 20 7c 20 53 51 4c ERR_ACCESS | SQL
3f080 49 54 45 5f 49 4f 45 52 52 5f 58 58 58 5d 20 65 ITE_IOERR_XXX] e
3f090 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 69 73 20 rror code.** is
3f0a0 72 65 74 75 72 6e 65 64 2e 20 49 6e 20 74 68 69 returned. In thi
3f0b0 73 20 63 61 73 65 20 74 68 65 20 65 72 72 6f 72 s case the error
3f0c0 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 code and an err
3f0d0 6f 72 20 6d 65 73 73 61 67 65 20 61 72 65 0a 2a or message are.*
3f0e0 2a 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68 65 * written to the
3f0f0 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 5b 64 61 destination [da
3f100 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3f110 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 74 75 n]..**.** A retu
3f120 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 rn of [SQLITE_BU
3f130 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c SY] or [SQLITE_L
3f140 4f 43 4b 45 44 5d 20 66 72 6f 6d 20 73 71 6c 69 OCKED] from sqli
3f150 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3f160 29 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 65 ) is.** not a pe
3f170 72 6d 61 6e 65 6e 74 20 65 72 72 6f 72 20 61 6e rmanent error an
3f180 64 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 d does not affec
3f190 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c t the return val
3f1a0 75 65 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 ue of.** sqlite3
3f1b0 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3f1c0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 ..**.** <b>sqlit
3f1d0 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e e3_backup_remain
3f1e0 69 6e 67 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 ing(), sqlite3_b
3f1f0 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 ackup_pagecount(
3f200 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 )</b>.**.** Each
3f210 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
3f220 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 73 _backup_step() s
3f230 65 74 73 20 74 77 6f 20 76 61 6c 75 65 73 20 73 ets two values s
3f240 74 6f 72 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 tored internally
3f250 0a 2a 2a 20 62 79 20 61 6e 20 5b 73 71 6c 69 74 .** by an [sqlit
3f260 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 e3_backup] objec
3f270 74 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 t. The number of
3f280 20 70 61 67 65 73 20 73 74 69 6c 6c 20 74 6f 20 pages still to
3f290 62 65 20 62 61 63 6b 65 64 0a 2a 2a 20 75 70 2c be backed.** up,
3f2a0 20 77 68 69 63 68 20 6d 61 79 20 62 65 20 71 75 which may be qu
3f2b0 65 72 69 65 64 20 62 79 20 73 71 6c 69 74 65 33 eried by sqlite3
3f2c0 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e 69 6e _backup_remainin
3f2d0 67 28 29 2c 20 61 6e 64 20 74 68 65 20 74 6f 74 g(), and the tot
3f2e0 61 6c 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 al.** number of
3f2f0 70 61 67 65 73 20 69 6e 20 74 68 65 20 73 6f 75 pages in the sou
3f300 72 63 65 20 64 61 74 61 62 61 73 65 20 66 69 6c rce database fil
3f310 65 2c 20 77 68 69 63 68 20 6d 61 79 20 62 65 20 e, which may be
3f320 71 75 65 72 69 65 64 20 62 79 0a 2a 2a 20 73 71 queried by.** sq
3f330 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 lite3_backup_pag
3f340 65 63 6f 75 6e 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 ecount()..**.**
3f350 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 The values retur
3f360 6e 65 64 20 62 79 20 74 68 65 73 65 20 66 75 6e ned by these fun
3f370 63 74 69 6f 6e 73 20 61 72 65 20 6f 6e 6c 79 20 ctions are only
3f380 75 70 64 61 74 65 64 20 62 79 0a 2a 2a 20 73 71 updated by.** sq
3f390 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3f3a0 70 28 29 2e 20 49 66 20 74 68 65 20 73 6f 75 72 p(). If the sour
3f3b0 63 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6d ce database is m
3f3c0 6f 64 69 66 69 65 64 20 64 75 72 69 6e 67 20 61 odified during a
3f3d0 20 62 61 63 6b 75 70 0a 2a 2a 20 6f 70 65 72 61 backup.** opera
3f3e0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 76 tion, then the v
3f3f0 61 6c 75 65 73 20 61 72 65 20 6e 6f 74 20 75 70 alues are not up
3f400 64 61 74 65 64 20 74 6f 20 61 63 63 6f 75 6e 74 dated to account
3f410 20 66 6f 72 20 61 6e 79 20 65 78 74 72 61 0a 2a for any extra.*
3f420 2a 20 70 61 67 65 73 20 74 68 61 74 20 6e 65 65 * pages that nee
3f430 64 20 74 6f 20 62 65 20 75 70 64 61 74 65 64 20 d to be updated
3f440 6f 72 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 or the size of t
3f450 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3f460 73 65 20 66 69 6c 65 0a 2a 2a 20 63 68 61 6e 67 se file.** chang
3f470 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 43 6f ing..**.** <b>Co
3f480 6e 63 75 72 72 65 6e 74 20 55 73 61 67 65 20 6f ncurrent Usage o
3f490 66 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c f Database Handl
3f4a0 65 73 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 es</b>.**.** The
3f4b0 20 73 6f 75 72 63 65 20 5b 64 61 74 61 62 61 73 source [databas
3f4c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6d 61 e connection] ma
3f4d0 79 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65 y be used by the
3f4e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 6f 72 application for
3f4f0 20 6f 74 68 65 72 0a 2a 2a 20 70 75 72 70 6f 73 other.** purpos
3f500 65 73 20 77 68 69 6c 65 20 61 20 62 61 63 6b 75 es while a backu
3f510 70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 75 p operation is u
3f520 6e 64 65 72 77 61 79 20 6f 72 20 62 65 69 6e 67 nderway or being
3f530 20 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a initialized..**
3f540 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f If SQLite is co
3f550 6d 70 69 6c 65 64 20 61 6e 64 20 63 6f 6e 66 69 mpiled and confi
3f560 67 75 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 gured to support
3f570 20 74 68 72 65 61 64 73 61 66 65 20 64 61 74 61 threadsafe data
3f580 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
3f590 6f 6e 73 2c 20 74 68 65 6e 20 74 68 65 20 73 6f ons, then the so
3f5a0 75 72 63 65 20 64 61 74 61 62 61 73 65 20 63 6f urce database co
3f5b0 6e 6e 65 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 nnection may be
3f5c0 75 73 65 64 20 63 6f 6e 63 75 72 72 65 6e 74 6c used concurrentl
3f5d0 79 0a 2a 2a 20 66 72 6f 6d 20 77 69 74 68 69 6e y.** from within
3f5e0 20 6f 74 68 65 72 20 74 68 72 65 61 64 73 2e 0a other threads..
3f5f0 2a 2a 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 **.** However, t
3f600 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
3f610 75 73 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 ust guarantee th
3f620 61 74 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 at the destinati
3f630 6f 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 on database.** c
3f640 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 onnection handle
3f650 20 69 73 20 6e 6f 74 20 70 61 73 73 65 64 20 74 is not passed t
3f660 6f 20 61 6e 79 20 6f 74 68 65 72 20 41 50 49 20 o any other API
3f670 28 62 79 20 61 6e 79 20 74 68 72 65 61 64 29 20 (by any thread)
3f680 61 66 74 65 72 20 0a 2a 2a 20 73 71 6c 69 74 65 after .** sqlite
3f690 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 20 3_backup_init()
3f6a0 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 20 62 65 is called and be
3f6b0 66 6f 72 65 20 74 68 65 20 63 6f 72 72 65 73 70 fore the corresp
3f6c0 6f 6e 64 69 6e 67 20 63 61 6c 6c 20 74 6f 0a 2a onding call to.*
3f6d0 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 * sqlite3_backup
3f6e0 5f 66 69 6e 69 73 68 28 29 2e 20 55 6e 66 6f 72 _finish(). Unfor
3f6f0 74 75 6e 61 74 65 6c 79 20 53 51 4c 69 74 65 20 tunately SQLite
3f700 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 does not current
3f710 6c 79 20 63 68 65 63 6b 0a 2a 2a 20 66 6f 72 20 ly check.** for
3f720 74 68 69 73 2c 20 69 66 20 74 68 65 20 61 70 70 this, if the app
3f730 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 75 73 lication does us
3f740 65 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f e the destinatio
3f750 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
3f760 65 63 74 69 6f 6e 5d 0a 2a 2a 20 66 6f 72 20 73 ection].** for s
3f770 6f 6d 65 20 6f 74 68 65 72 20 70 75 72 70 6f 73 ome other purpos
3f780 65 20 64 75 72 69 6e 67 20 61 20 62 61 63 6b 75 e during a backu
3f790 70 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 69 p operation, thi
3f7a0 6e 67 73 20 6d 61 79 20 61 70 70 65 61 72 20 74 ngs may appear t
3f7b0 6f 0a 2a 2a 20 77 6f 72 6b 20 63 6f 72 72 65 63 o.** work correc
3f7c0 74 6c 79 20 62 75 74 20 69 6e 20 66 61 63 74 20 tly but in fact
3f7d0 62 65 20 73 75 62 74 6c 79 20 6d 61 6c 66 75 6e be subtly malfun
3f7e0 63 74 69 6f 6e 69 6e 67 2e 20 20 55 73 65 20 6f ctioning. Use o
3f7f0 66 20 74 68 65 0a 2a 2a 20 64 65 73 74 69 6e 61 f the.** destina
3f800 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f tion database co
3f810 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 61 nnection while a
3f820 20 62 61 63 6b 75 70 20 69 73 20 69 6e 20 70 72 backup is in pr
3f830 6f 67 72 65 73 73 20 6d 69 67 68 74 0a 2a 2a 20 ogress might.**
3f840 61 6c 73 6f 20 63 61 75 73 65 20 61 20 6d 75 74 also cause a mut
3f850 65 78 20 64 65 61 64 6c 6f 63 6b 2e 0a 2a 2a 0a ex deadlock..**.
3f860 2a 2a 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 ** Furthermore,
3f870 69 66 20 72 75 6e 6e 69 6e 67 20 69 6e 20 5b 73 if running in [s
3f880 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
3f890 5d 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ], the applicati
3f8a0 6f 6e 20 6d 75 73 74 0a 2a 2a 20 67 75 61 72 61 on must.** guara
3f8b0 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 73 68 ntee that the sh
3f8c0 61 72 65 64 20 63 61 63 68 65 20 75 73 65 64 20 ared cache used
3f8d0 62 79 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 by the destinati
3f8e0 6f 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 on database.** i
3f8f0 73 20 6e 6f 74 20 61 63 63 65 73 73 65 64 20 77 s not accessed w
3f900 68 69 6c 65 20 74 68 65 20 62 61 63 6b 75 70 20 hile the backup
3f910 69 73 20 72 75 6e 6e 69 6e 67 2e 20 49 6e 20 70 is running. In p
3f920 72 61 63 74 69 63 65 20 74 68 69 73 20 6d 65 61 ractice this mea
3f930 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 61 ns.** that the a
3f940 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
3f950 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 guarantee that t
3f960 68 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 he file-system f
3f970 69 6c 65 20 62 65 69 6e 67 20 0a 2a 2a 20 62 61 ile being .** ba
3f980 63 6b 65 64 20 75 70 20 74 6f 20 69 73 20 6e 6f cked up to is no
3f990 74 20 61 63 63 65 73 73 65 64 20 62 79 20 61 6e t accessed by an
3f9a0 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 74 y connection wit
3f9b0 68 69 6e 20 74 68 65 20 70 72 6f 63 65 73 73 2c hin the process,
3f9c0 0a 2a 2a 20 6e 6f 74 20 6a 75 73 74 20 74 68 65 .** not just the
3f9d0 20 73 70 65 63 69 66 69 63 20 63 6f 6e 6e 65 63 specific connec
3f9e0 74 69 6f 6e 20 74 68 61 74 20 77 61 73 20 70 61 tion that was pa
3f9f0 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f ssed to sqlite3_
3fa00 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2e 0a 2a backup_init()..*
3fa10 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
3fa20 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 3_backup] object
3fa30 20 69 74 73 65 6c 66 20 69 73 20 70 61 72 74 69 itself is parti
3fa40 61 6c 6c 79 20 74 68 72 65 61 64 73 61 66 65 2e ally threadsafe.
3fa50 20 4d 75 6c 74 69 70 6c 65 20 0a 2a 2a 20 74 68 Multiple .** th
3fa60 72 65 61 64 73 20 6d 61 79 20 73 61 66 65 6c 79 reads may safely
3fa70 20 6d 61 6b 65 20 6d 75 6c 74 69 70 6c 65 20 63 make multiple c
3fa80 6f 6e 63 75 72 72 65 6e 74 20 63 61 6c 6c 73 20 oncurrent calls
3fa90 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3faa0 70 5f 73 74 65 70 28 29 2e 0a 2a 2a 20 48 6f 77 p_step()..** How
3fab0 65 76 65 72 2c 20 74 68 65 20 73 71 6c 69 74 65 ever, the sqlite
3fac0 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e 69 3_backup_remaini
3fad0 6e 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ng() and sqlite3
3fae0 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e _backup_pagecoun
3faf0 74 28 29 0a 2a 2a 20 41 50 49 73 20 61 72 65 20 t().** APIs are
3fb00 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 73 70 65 not strictly spe
3fb10 61 6b 69 6e 67 20 74 68 72 65 61 64 73 61 66 65 aking threadsafe
3fb20 2e 20 49 66 20 74 68 65 79 20 61 72 65 20 69 6e . If they are in
3fb30 76 6f 6b 65 64 20 61 74 20 74 68 65 0a 2a 2a 20 voked at the.**
3fb40 73 61 6d 65 20 74 69 6d 65 20 61 73 20 61 6e 6f same time as ano
3fb50 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 69 ther thread is i
3fb60 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f nvoking sqlite3_
3fb70 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 69 74 backup_step() it
3fb80 20 69 73 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 is.** possible
3fb90 74 68 61 74 20 74 68 65 79 20 72 65 74 75 72 6e that they return
3fba0 20 69 6e 76 61 6c 69 64 20 76 61 6c 75 65 73 2e invalid values.
3fbb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 .*/.SQLITE_API s
3fbc0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 73 qlite3_backup *s
3fbd0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e qlite3_backup_in
3fbe0 69 74 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 70 it(. sqlite3 *p
3fbf0 44 65 73 74 2c 20 20 20 20 20 20 20 20 20 20 20 Dest,
3fc00 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3fc10 44 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 Destination data
3fc20 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
3fc30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 65 const char *zDe
3fc40 73 74 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 stName,
3fc50 20 20 20 20 20 20 20 20 2f 2a 20 44 65 73 74 69 /* Desti
3fc60 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 nation database
3fc70 6e 61 6d 65 20 2a 2f 0a 20 20 73 71 6c 69 74 65 name */. sqlite
3fc80 33 20 2a 70 53 6f 75 72 63 65 2c 20 20 20 20 20 3 *pSource,
3fc90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fca0 20 2f 2a 20 53 6f 75 72 63 65 20 64 61 74 61 62 /* Source datab
3fcb0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
3fcc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 6f 75 const char *zSou
3fcd0 72 63 65 4e 61 6d 65 20 20 20 20 20 20 20 20 20 rceName
3fce0 20 20 20 20 20 20 20 2f 2a 20 53 6f 75 72 63 65 /* Source
3fcf0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 2a database name *
3fd00 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
3fd10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b int sqlite3_back
3fd20 75 70 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f up_step(sqlite3_
3fd30 62 61 63 6b 75 70 20 2a 70 2c 20 69 6e 74 20 6e backup *p, int n
3fd40 50 61 67 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 Page);.SQLITE_AP
3fd50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 I int sqlite3_ba
3fd60 63 6b 75 70 5f 66 69 6e 69 73 68 28 73 71 6c 69 ckup_finish(sqli
3fd70 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 29 3b 0a te3_backup *p);.
3fd80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
3fd90 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 qlite3_backup_re
3fda0 6d 61 69 6e 69 6e 67 28 73 71 6c 69 74 65 33 5f maining(sqlite3_
3fdb0 62 61 63 6b 75 70 20 2a 70 29 3b 0a 53 51 4c 49 backup *p);.SQLI
3fdc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
3fdd0 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 6f e3_backup_pageco
3fde0 75 6e 74 28 73 71 6c 69 74 65 33 5f 62 61 63 6b unt(sqlite3_back
3fdf0 75 70 20 2a 70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 up *p);../*.** C
3fe00 41 50 49 33 52 45 46 3a 20 55 6e 6c 6f 63 6b 20 API3REF: Unlock
3fe10 4e 6f 74 69 66 69 63 61 74 69 6f 6e 0a 2a 2a 20 Notification.**
3fe20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
3fe30 2a 2a 20 57 68 65 6e 20 72 75 6e 6e 69 6e 67 20 ** When running
3fe40 69 6e 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 in shared-cache
3fe50 6d 6f 64 65 2c 20 61 20 64 61 74 61 62 61 73 65 mode, a database
3fe60 20 6f 70 65 72 61 74 69 6f 6e 20 6d 61 79 20 66 operation may f
3fe70 61 69 6c 20 77 69 74 68 0a 2a 2a 20 61 6e 20 5b ail with.** an [
3fe80 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 65 SQLITE_LOCKED] e
3fe90 72 72 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 rror if the requ
3fea0 69 72 65 64 20 6c 6f 63 6b 73 20 6f 6e 20 74 68 ired locks on th
3feb0 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6f e shared-cache o
3fec0 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 r.** individual
3fed0 74 61 62 6c 65 73 20 77 69 74 68 69 6e 20 74 68 tables within th
3fee0 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 63 e shared-cache c
3fef0 61 6e 6e 6f 74 20 62 65 20 6f 62 74 61 69 6e 65 annot be obtaine
3ff00 64 2e 20 53 65 65 0a 2a 2a 20 5b 53 51 4c 69 74 d. See.** [SQLit
3ff10 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d e Shared-Cache M
3ff20 6f 64 65 5d 20 66 6f 72 20 61 20 64 65 73 63 72 ode] for a descr
3ff30 69 70 74 69 6f 6e 20 6f 66 20 73 68 61 72 65 64 iption of shared
3ff40 2d 63 61 63 68 65 20 6c 6f 63 6b 69 6e 67 2e 20 -cache locking.
3ff50 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 79 .** This API may
3ff60 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 be used to regi
3ff70 73 74 65 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 ster a callback
3ff80 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
3ff90 20 69 6e 76 6f 6b 65 20 0a 2a 2a 20 77 68 65 6e invoke .** when
3ffa0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 the connection
3ffb0 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64 69 6e currently holdin
3ffc0 67 20 74 68 65 20 72 65 71 75 69 72 65 64 20 6c g the required l
3ffd0 6f 63 6b 20 72 65 6c 69 6e 71 75 69 73 68 65 73 ock relinquishes
3ffe0 20 69 74 2e 0a 2a 2a 20 54 68 69 73 20 41 50 49 it..** This API
3fff0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
40000 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
40010 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
40020 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
40030 54 45 5f 45 4e 41 42 4c 45 5f 55 4e 4c 4f 43 4b TE_ENABLE_UNLOCK
40040 5f 4e 4f 54 49 46 59 5d 20 43 2d 70 72 65 70 72 _NOTIFY] C-prepr
40050 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 ocessor symbol d
40060 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 efined..**.** Se
40070 65 20 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 e Also: [Using t
40080 68 65 20 53 51 4c 69 74 65 20 55 6e 6c 6f 63 6b he SQLite Unlock
40090 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 46 65 Notification Fe
400a0 61 74 75 72 65 5d 2e 0a 2a 2a 0a 2a 2a 20 53 68 ature]..**.** Sh
400b0 61 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b 73 ared-cache locks
400c0 20 61 72 65 20 72 65 6c 65 61 73 65 64 20 77 68 are released wh
400d0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f en a database co
400e0 6e 6e 65 63 74 69 6f 6e 20 63 6f 6e 63 6c 75 64 nnection conclud
400f0 65 73 0a 2a 2a 20 69 74 73 20 63 75 72 72 65 6e es.** its curren
40100 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 65 t transaction, e
40110 69 74 68 65 72 20 62 79 20 63 6f 6d 6d 69 74 74 ither by committ
40120 69 6e 67 20 69 74 20 6f 72 20 72 6f 6c 6c 69 6e ing it or rollin
40130 67 20 69 74 20 62 61 63 6b 2e 20 0a 2a 2a 0a 2a g it back. .**.*
40140 2a 20 57 68 65 6e 20 61 20 63 6f 6e 6e 65 63 74 * When a connect
40150 69 6f 6e 20 28 6b 6e 6f 77 6e 20 61 73 20 74 68 ion (known as th
40160 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 e blocked connec
40170 74 69 6f 6e 29 20 66 61 69 6c 73 20 74 6f 20 6f tion) fails to o
40180 62 74 61 69 6e 20 61 0a 2a 2a 20 73 68 61 72 65 btain a.** share
40190 64 2d 63 61 63 68 65 20 6c 6f 63 6b 20 61 6e 64 d-cache lock and
401a0 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 69 SQLITE_LOCKED i
401b0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 s returned to th
401c0 65 20 63 61 6c 6c 65 72 2c 20 74 68 65 0a 2a 2a e caller, the.**
401d0 20 69 64 65 6e 74 69 74 79 20 6f 66 20 74 68 65 identity of the
401e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
401f0 74 69 6f 6e 20 28 74 68 65 20 62 6c 6f 63 6b 69 tion (the blocki
40200 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 29 20 74 ng connection) t
40210 68 61 74 0a 2a 2a 20 68 61 73 20 6c 6f 63 6b 65 hat.** has locke
40220 64 20 74 68 65 20 72 65 71 75 69 72 65 64 20 72 d the required r
40230 65 73 6f 75 72 63 65 20 69 73 20 73 74 6f 72 65 esource is store
40240 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 41 66 d internally. Af
40250 74 65 72 20 61 6e 20 0a 2a 2a 20 61 70 70 6c 69 ter an .** appli
40260 63 61 74 69 6f 6e 20 72 65 63 65 69 76 65 73 20 cation receives
40270 61 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 an SQLITE_LOCKED
40280 20 65 72 72 6f 72 2c 20 69 74 20 6d 61 79 20 63 error, it may c
40290 61 6c 6c 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 all the.** sqlit
402a0 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 e3_unlock_notify
402b0 28 29 20 6d 65 74 68 6f 64 20 77 69 74 68 20 74 () method with t
402c0 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 he blocked conne
402d0 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 61 73 20 ction handle as
402e0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61 72 .** the first ar
402f0 67 75 6d 65 6e 74 20 74 6f 20 72 65 67 69 73 74 gument to regist
40300 65 72 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 er for a callbac
40310 6b 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 69 k that will be i
40320 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 nvoked.** when t
40330 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e he blocking conn
40340 65 63 74 69 6f 6e 73 20 63 75 72 72 65 6e 74 20 ections current
40350 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 transaction is c
40360 6f 6e 63 6c 75 64 65 64 2e 20 54 68 65 0a 2a 2a oncluded. The.**
40370 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
40380 6f 6b 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e oked from within
40390 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
403a0 65 70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ep] or [sqlite3_
403b0 63 6c 6f 73 65 5d 0a 2a 2a 20 63 61 6c 6c 20 74 close].** call t
403c0 68 61 74 20 63 6f 6e 63 6c 75 64 65 73 20 74 68 hat concludes th
403d0 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 e blocking conne
403e0 63 74 69 6f 6e 73 20 74 72 61 6e 73 61 63 74 69 ctions transacti
403f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c on..**.** If sql
40400 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
40410 66 79 28 29 20 69 73 20 63 61 6c 6c 65 64 20 69 fy() is called i
40420 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
40430 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 0a ed application,.
40440 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 63 68 ** there is a ch
40450 61 6e 63 65 20 74 68 61 74 20 74 68 65 20 62 6c ance that the bl
40460 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f ocking connectio
40470 6e 20 77 69 6c 6c 20 68 61 76 65 20 61 6c 72 65 n will have alre
40480 61 64 79 0a 2a 2a 20 63 6f 6e 63 6c 75 64 65 64 ady.** concluded
40490 20 69 74 73 20 74 72 61 6e 73 61 63 74 69 6f 6e its transaction
404a0 20 62 79 20 74 68 65 20 74 69 6d 65 20 73 71 6c by the time sql
404b0 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
404c0 66 79 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 2e fy() is invoked.
404d0 0a 2a 2a 20 49 66 20 74 68 69 73 20 68 61 70 70 .** If this happ
404e0 65 6e 73 2c 20 74 68 65 6e 20 74 68 65 20 73 70 ens, then the sp
404f0 65 63 69 66 69 65 64 20 63 61 6c 6c 62 61 63 6b ecified callback
40500 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6d 6d 65 is invoked imme
40510 64 69 61 74 65 6c 79 2c 0a 2a 2a 20 66 72 6f 6d diately,.** from
40520 20 77 69 74 68 69 6e 20 74 68 65 20 63 61 6c 6c within the call
40530 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f to sqlite3_unlo
40540 63 6b 5f 6e 6f 74 69 66 79 28 29 2e 0a 2a 2a 0a ck_notify()..**.
40550 2a 2a 20 49 66 20 74 68 65 20 62 6c 6f 63 6b 65 ** If the blocke
40560 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 d connection is
40570 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 6f 62 attempting to ob
40580 74 61 69 6e 20 61 20 77 72 69 74 65 2d 6c 6f 63 tain a write-loc
40590 6b 20 6f 6e 20 61 0a 2a 2a 20 73 68 61 72 65 64 k on a.** shared
405a0 2d 63 61 63 68 65 20 74 61 62 6c 65 2c 20 61 6e -cache table, an
405b0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 d more than one
405c0 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e other connection
405d0 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64 73 currently holds
405e0 0a 2a 2a 20 61 20 72 65 61 64 2d 6c 6f 63 6b 20 .** a read-lock
405f0 6f 6e 20 74 68 65 20 73 61 6d 65 20 74 61 62 6c on the same tabl
40600 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 e, then SQLite a
40610 72 62 69 74 72 61 72 69 6c 79 20 73 65 6c 65 63 rbitrarily selec
40620 74 73 20 6f 6e 65 20 6f 66 20 0a 2a 2a 20 74 68 ts one of .** th
40630 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 e other connecti
40640 6f 6e 73 20 74 6f 20 75 73 65 20 61 73 20 74 68 ons to use as th
40650 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 e blocking conne
40660 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ction..**.** The
40670 72 65 20 6d 61 79 20 62 65 20 61 74 20 6d 6f 73 re may be at mos
40680 74 20 6f 6e 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 t one unlock-not
40690 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 ify callback reg
406a0 69 73 74 65 72 65 64 20 62 79 20 61 20 0a 2a 2a istered by a .**
406b0 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 blocked connect
406c0 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 65 33 5f ion. If sqlite3_
406d0 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
406e0 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 is called when t
406f0 68 65 0a 2a 2a 20 62 6c 6f 63 6b 65 64 20 63 6f he.** blocked co
40700 6e 6e 65 63 74 69 6f 6e 20 61 6c 72 65 61 64 79 nnection already
40710 20 68 61 73 20 61 20 72 65 67 69 73 74 65 72 65 has a registere
40720 64 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 d unlock-notify
40730 63 61 6c 6c 62 61 63 6b 2c 0a 2a 2a 20 74 68 65 callback,.** the
40740 6e 20 74 68 65 20 6e 65 77 20 63 61 6c 6c 62 61 n the new callba
40750 63 6b 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 ck replaces the
40760 6f 6c 64 2e 20 49 66 20 73 71 6c 69 74 65 33 5f old. If sqlite3_
40770 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
40780 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 69 74 is.** called wit
40790 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
407a0 20 61 73 20 69 74 73 20 73 65 63 6f 6e 64 20 61 as its second a
407b0 72 67 75 6d 65 6e 74 2c 20 74 68 65 6e 20 61 6e rgument, then an
407c0 79 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 75 6e y existing.** un
407d0 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
407e0 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65 back is cancelle
407f0 64 2e 20 54 68 65 20 62 6c 6f 63 6b 65 64 20 63 d. The blocked c
40800 6f 6e 6e 65 63 74 69 6f 6e 73 20 0a 2a 2a 20 75 onnections .** u
40810 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c nlock-notify cal
40820 6c 62 61 63 6b 20 6d 61 79 20 61 6c 73 6f 20 62 lback may also b
40830 65 20 63 61 6e 63 65 6c 65 64 20 62 79 20 63 6c e canceled by cl
40840 6f 73 69 6e 67 20 74 68 65 20 62 6c 6f 63 6b 65 osing the blocke
40850 64 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 d.** connection
40860 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
40870 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 lose()]..**.** T
40880 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 he unlock-notify
40890 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
408a0 20 72 65 65 6e 74 72 61 6e 74 2e 20 49 66 20 61 reentrant. If a
408b0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e n application in
408c0 76 6f 6b 65 73 0a 2a 2a 20 61 6e 79 20 73 71 6c vokes.** any sql
408d0 69 74 65 33 5f 78 78 78 20 41 50 49 20 66 75 6e ite3_xxx API fun
408e0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 77 69 74 68 ctions from with
408f0 69 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 in an unlock-not
40900 69 66 79 20 63 61 6c 6c 62 61 63 6b 2c 20 61 0a ify callback, a.
40910 2a 2a 20 63 72 61 73 68 20 6f 72 20 64 65 61 64 ** crash or dead
40920 6c 6f 63 6b 20 6d 61 79 20 62 65 20 74 68 65 20 lock may be the
40930 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 55 6e result..**.** Un
40940 6c 65 73 73 20 64 65 61 64 6c 6f 63 6b 20 69 73 less deadlock is
40950 20 64 65 74 65 63 74 65 64 20 28 73 65 65 20 62 detected (see b
40960 65 6c 6f 77 29 2c 20 73 71 6c 69 74 65 33 5f 75 elow), sqlite3_u
40970 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 61 nlock_notify() a
40980 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 73 lways.** returns
40990 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a SQLITE_OK..**.*
409a0 2a 20 3c 62 3e 43 61 6c 6c 62 61 63 6b 20 49 6e * <b>Callback In
409b0 76 6f 63 61 74 69 6f 6e 20 44 65 74 61 69 6c 73 vocation Details
409c0 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 </b>.**.** When
409d0 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 an unlock-notify
409e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 72 65 67 callback is reg
409f0 69 73 74 65 72 65 64 2c 20 74 68 65 20 61 70 70 istered, the app
40a00 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 lication provide
40a10 73 20 61 20 0a 2a 2a 20 73 69 6e 67 6c 65 20 76 s a .** single v
40a20 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 74 68 61 oid* pointer tha
40a30 74 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 74 t is passed to t
40a40 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 68 65 6e he callback when
40a50 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a it is invoked..
40a60 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 ** However, the
40a70 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65 signature of the
40a80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
40a90 6f 6e 20 61 6c 6c 6f 77 73 20 53 51 4c 69 74 65 on allows SQLite
40aa0 20 74 6f 20 70 61 73 73 0a 2a 2a 20 69 74 20 61 to pass.** it a
40ab0 6e 20 61 72 72 61 79 20 6f 66 20 76 6f 69 64 2a n array of void*
40ac0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
40ad0 73 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 s. The first arg
40ae0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a ument passed to.
40af0 2a 2a 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 ** an unlock-not
40b00 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ify callback is
40b10 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
40b20 61 72 72 61 79 20 6f 66 20 76 6f 69 64 2a 20 70 array of void* p
40b30 6f 69 6e 74 65 72 73 2c 0a 2a 2a 20 61 6e 64 20 ointers,.** and
40b40 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 the second is th
40b50 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 e number of entr
40b60 69 65 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 ies in the array
40b70 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 62 ..**.** When a b
40b80 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 locking connecti
40b90 6f 6e 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 ons transaction
40ba0 69 73 20 63 6f 6e 63 6c 75 64 65 64 2c 20 74 68 is concluded, th
40bb0 65 72 65 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f ere may be.** mo
40bc0 72 65 20 74 68 61 6e 20 6f 6e 65 20 62 6c 6f 63 re than one bloc
40bd0 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ked connection t
40be0 68 61 74 20 68 61 73 20 72 65 67 69 73 74 65 72 hat has register
40bf0 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b ed for an unlock
40c00 2d 6e 6f 74 69 66 79 0a 2a 2a 20 63 61 6c 6c 62 -notify.** callb
40c10 61 63 6b 2e 20 49 66 20 74 77 6f 20 6f 72 20 6d ack. If two or m
40c20 6f 72 65 20 73 75 63 68 20 62 6c 6f 63 6b 65 64 ore such blocked
40c30 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 68 61 76 connections hav
40c40 65 20 73 70 65 63 69 66 69 65 64 20 74 68 65 0a e specified the.
40c50 2a 2a 20 73 61 6d 65 20 63 61 6c 6c 62 61 63 6b ** same callback
40c60 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 65 6e 20 function, then
40c70 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b instead of invok
40c80 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ing the callback
40c90 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 6c function.** mul
40ca0 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 69 74 20 tiple times, it
40cb0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 is invoked once
40cc0 77 69 74 68 20 74 68 65 20 73 65 74 20 6f 66 20 with the set of
40cd0 76 6f 69 64 2a 20 63 6f 6e 74 65 78 74 20 70 6f void* context po
40ce0 69 6e 74 65 72 73 0a 2a 2a 20 73 70 65 63 69 66 inters.** specif
40cf0 69 65 64 20 62 79 20 74 68 65 20 62 6c 6f 63 6b ied by the block
40d00 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 ed connections b
40d10 75 6e 64 6c 65 64 20 74 6f 67 65 74 68 65 72 20 undled together
40d20 69 6e 74 6f 20 61 6e 20 61 72 72 61 79 2e 0a 2a into an array..*
40d30 2a 20 54 68 69 73 20 67 69 76 65 73 20 74 68 65 * This gives the
40d40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 61 6e 20 application an
40d50 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 20 70 opportunity to p
40d60 72 69 6f 72 69 74 69 7a 65 20 61 6e 79 20 61 63 rioritize any ac
40d70 74 69 6f 6e 73 20 0a 2a 2a 20 72 65 6c 61 74 65 tions .** relate
40d80 64 20 74 6f 20 74 68 65 20 73 65 74 20 6f 66 20 d to the set of
40d90 75 6e 62 6c 6f 63 6b 65 64 20 64 61 74 61 62 61 unblocked databa
40da0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a se connections..
40db0 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 61 64 6c 6f 63 **.** <b>Deadloc
40dc0 6b 20 44 65 74 65 63 74 69 6f 6e 3c 2f 62 3e 0a k Detection</b>.
40dd0 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67 20 74 **.** Assuming t
40de0 68 61 74 20 61 66 74 65 72 20 72 65 67 69 73 74 hat after regist
40df0 65 72 69 6e 67 20 66 6f 72 20 61 6e 20 75 6e 6c ering for an unl
40e00 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 ock-notify callb
40e10 61 63 6b 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 ack a .** databa
40e20 73 65 20 77 61 69 74 73 20 66 6f 72 20 74 68 65 se waits for the
40e30 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 callback to be
40e40 69 73 73 75 65 64 20 62 65 66 6f 72 65 20 74 61 issued before ta
40e50 6b 69 6e 67 20 61 6e 79 20 66 75 72 74 68 65 72 king any further
40e60 0a 2a 2a 20 61 63 74 69 6f 6e 20 28 61 20 72 65 .** action (a re
40e70 61 73 6f 6e 61 62 6c 65 20 61 73 73 75 6d 70 74 asonable assumpt
40e80 69 6f 6e 29 2c 20 74 68 65 6e 20 75 73 69 6e 67 ion), then using
40e90 20 74 68 69 73 20 41 50 49 20 6d 61 79 20 63 61 this API may ca
40ea0 75 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 use the.** appli
40eb0 63 61 74 69 6f 6e 20 74 6f 20 64 65 61 64 6c 6f cation to deadlo
40ec0 63 6b 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c ck. For example,
40ed0 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 58 if connection X
40ee0 20 69 73 20 77 61 69 74 69 6e 67 20 66 6f 72 0a is waiting for.
40ef0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 59 27 ** connection Y'
40f00 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f s transaction to
40f10 20 62 65 20 63 6f 6e 63 6c 75 64 65 64 2c 20 61 be concluded, a
40f20 6e 64 20 73 69 6d 69 6c 61 72 6c 79 20 63 6f 6e nd similarly con
40f30 6e 65 63 74 69 6f 6e 0a 2a 2a 20 59 20 69 73 20 nection.** Y is
40f40 77 61 69 74 69 6e 67 20 6f 6e 20 63 6f 6e 6e 65 waiting on conne
40f50 63 74 69 6f 6e 20 58 27 73 20 74 72 61 6e 73 61 ction X's transa
40f60 63 74 69 6f 6e 2c 20 74 68 65 6e 20 6e 65 69 74 ction, then neit
40f70 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a her connection.*
40f80 2a 20 77 69 6c 6c 20 70 72 6f 63 65 65 64 20 61 * will proceed a
40f90 6e 64 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 nd the system ma
40fa0 79 20 72 65 6d 61 69 6e 20 64 65 61 64 6c 6f 63 y remain deadloc
40fb0 6b 65 64 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 ked indefinitely
40fc0 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 ..**.** To avoid
40fd0 20 74 68 69 73 20 73 63 65 6e 61 72 69 6f 2c 20 this scenario,
40fe0 74 68 65 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f the sqlite3_unlo
40ff0 63 6b 5f 6e 6f 74 69 66 79 28 29 20 70 65 72 66 ck_notify() perf
41000 6f 72 6d 73 20 64 65 61 64 6c 6f 63 6b 0a 2a 2a orms deadlock.**
41010 20 64 65 74 65 63 74 69 6f 6e 2e 20 49 66 20 61 detection. If a
41020 20 67 69 76 65 6e 20 63 61 6c 6c 20 74 6f 20 73 given call to s
41030 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
41040 74 69 66 79 28 29 20 77 6f 75 6c 64 20 70 75 74 tify() would put
41050 20 74 68 65 0a 2a 2a 20 73 79 73 74 65 6d 20 69 the.** system i
41060 6e 20 61 20 64 65 61 64 6c 6f 63 6b 65 64 20 73 n a deadlocked s
41070 74 61 74 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 tate, then SQLIT
41080 45 5f 4c 4f 43 4b 45 44 20 69 73 20 72 65 74 75 E_LOCKED is retu
41090 72 6e 65 64 20 61 6e 64 20 6e 6f 0a 2a 2a 20 75 rned and no.** u
410a0 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c nlock-notify cal
410b0 6c 62 61 63 6b 20 69 73 20 72 65 67 69 73 74 65 lback is registe
410c0 72 65 64 2e 20 54 68 65 20 73 79 73 74 65 6d 20 red. The system
410d0 69 73 20 73 61 69 64 20 74 6f 20 62 65 20 69 6e is said to be in
410e0 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 65 64 .** a deadlocked
410f0 20 73 74 61 74 65 20 69 66 20 63 6f 6e 6e 65 63 state if connec
41100 74 69 6f 6e 20 41 20 68 61 73 20 72 65 67 69 73 tion A has regis
41110 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c tered for an unl
41120 6f 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a 20 63 61 ock-notify.** ca
41130 6c 6c 62 61 63 6b 20 6f 6e 20 74 68 65 20 63 6f llback on the co
41140 6e 63 6c 75 73 69 6f 6e 20 6f 66 20 63 6f 6e 6e nclusion of conn
41150 65 63 74 69 6f 6e 20 42 27 73 20 74 72 61 6e 73 ection B's trans
41160 61 63 74 69 6f 6e 2c 20 61 6e 64 20 63 6f 6e 6e action, and conn
41170 65 63 74 69 6f 6e 0a 2a 2a 20 42 20 68 61 73 20 ection.** B has
41180 69 74 73 65 6c 66 20 72 65 67 69 73 74 65 72 65 itself registere
41190 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d d for an unlock-
411a0 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
411b0 77 68 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a when connection.
411c0 2a 2a 20 41 27 73 20 74 72 61 6e 73 61 63 74 69 ** A's transacti
411d0 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 65 64 2e on is concluded.
411e0 20 49 6e 64 69 72 65 63 74 20 64 65 61 64 6c 6f Indirect deadlo
411f0 63 6b 20 69 73 20 61 6c 73 6f 20 64 65 74 65 63 ck is also detec
41200 74 65 64 2c 20 73 6f 0a 2a 2a 20 74 68 65 20 73 ted, so.** the s
41210 79 73 74 65 6d 20 69 73 20 61 6c 73 6f 20 63 6f ystem is also co
41220 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 64 nsidered to be d
41230 65 61 64 6c 6f 63 6b 65 64 20 69 66 20 63 6f 6e eadlocked if con
41240 6e 65 63 74 69 6f 6e 20 42 20 68 61 73 0a 2a 2a nection B has.**
41250 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 20 registered for
41260 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 an unlock-notify
41270 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 74 68 65 callback on the
41280 20 63 6f 6e 63 6c 75 73 69 6f 6e 20 6f 66 20 63 conclusion of c
41290 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 27 73 onnection.** C's
412a0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 77 68 transaction, wh
412b0 65 72 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 43 ere connection C
412c0 20 69 73 20 77 61 69 74 69 6e 67 20 6f 6e 20 63 is waiting on c
412d0 6f 6e 6e 65 63 74 69 6f 6e 20 41 2e 20 41 6e 79 onnection A. Any
412e0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 6c 65 .** number of le
412f0 76 65 6c 73 20 6f 66 20 69 6e 64 69 72 65 63 74 vels of indirect
41300 69 6f 6e 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e ion are allowed.
41310 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 22 44 .**.** <b>The "D
41320 52 4f 50 20 54 41 42 4c 45 22 20 45 78 63 65 70 ROP TABLE" Excep
41330 74 69 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 tion</b>.**.** W
41340 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 hen a call to [s
41350 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 qlite3_step()] r
41360 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4c 4f eturns SQLITE_LO
41370 43 4b 45 44 2c 20 69 74 20 69 73 20 61 6c 6d 6f CKED, it is almo
41380 73 74 20 0a 2a 2a 20 61 6c 77 61 79 73 20 61 70 st .** always ap
41390 70 72 6f 70 72 69 61 74 65 20 74 6f 20 63 61 6c propriate to cal
413a0 6c 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b l sqlite3_unlock
413b0 5f 6e 6f 74 69 66 79 28 29 2e 20 54 68 65 72 65 _notify(). There
413c0 20 69 73 20 68 6f 77 65 76 65 72 2c 0a 2a 2a 20 is however,.**
413d0 6f 6e 65 20 65 78 63 65 70 74 69 6f 6e 2e 20 57 one exception. W
413e0 68 65 6e 20 65 78 65 63 75 74 69 6e 67 20 61 20 hen executing a
413f0 22 44 52 4f 50 20 54 41 42 4c 45 22 20 6f 72 20 "DROP TABLE" or
41400 22 44 52 4f 50 20 49 4e 44 45 58 22 20 73 74 61 "DROP INDEX" sta
41410 74 65 6d 65 6e 74 2c 0a 2a 2a 20 53 51 4c 69 74 tement,.** SQLit
41420 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 65 72 e checks if ther
41430 65 20 61 72 65 20 61 6e 79 20 63 75 72 72 65 6e e are any curren
41440 74 6c 79 20 65 78 65 63 75 74 69 6e 67 20 53 45 tly executing SE
41450 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 0a LECT statements.
41460 2a 2a 20 74 68 61 74 20 62 65 6c 6f 6e 67 20 74 ** that belong t
41470 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 6e 65 o the same conne
41480 63 74 69 6f 6e 2e 20 49 66 20 74 68 65 72 65 20 ction. If there
41490 61 72 65 2c 20 53 51 4c 49 54 45 5f 4c 4f 43 4b are, SQLITE_LOCK
414a0 45 44 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 ED is.** returne
414b0 64 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 d. In this case
414c0 74 68 65 72 65 20 69 73 20 6e 6f 20 22 62 6c 6f there is no "blo
414d0 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
414e0 22 2c 20 73 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a ", so invoking.*
414f0 2a 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b * sqlite3_unlock
41500 5f 6e 6f 74 69 66 79 28 29 20 72 65 73 75 6c 74 _notify() result
41510 73 20 69 6e 20 74 68 65 20 75 6e 6c 6f 63 6b 2d s in the unlock-
41520 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
41530 62 65 69 6e 67 0a 2a 2a 20 69 6e 76 6f 6b 65 64 being.** invoked
41540 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 49 66 immediately. If
41550 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
41560 20 74 68 65 6e 20 72 65 2d 61 74 74 65 6d 70 74 then re-attempt
41570 73 20 74 68 65 20 22 44 52 4f 50 20 54 41 42 4c s the "DROP TABL
41580 45 22 0a 2a 2a 20 6f 72 20 22 44 52 4f 50 20 49 E".** or "DROP I
41590 4e 44 45 58 22 20 71 75 65 72 79 2c 20 61 6e 20 NDEX" query, an
415a0 69 6e 66 69 6e 69 74 65 20 6c 6f 6f 70 20 6d 69 infinite loop mi
415b0 67 68 74 20 62 65 20 74 68 65 20 72 65 73 75 6c ght be the resul
415c0 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 77 61 79 t..**.** One way
415d0 20 61 72 6f 75 6e 64 20 74 68 69 73 20 70 72 6f around this pro
415e0 62 6c 65 6d 20 69 73 20 74 6f 20 63 68 65 63 6b blem is to check
415f0 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 65 72 the extended er
41600 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 6e 65 ror code returne
41610 64 0a 2a 2a 20 62 79 20 61 6e 20 73 71 6c 69 74 d.** by an sqlit
41620 65 33 5f 73 74 65 70 28 29 20 63 61 6c 6c 2e 20 e3_step() call.
41630 49 66 20 74 68 65 72 65 20 69 73 20 61 20 62 6c If there is a bl
41640 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f ocking connectio
41650 6e 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 65 n, then the.** e
41660 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
41670 64 65 20 69 73 20 73 65 74 20 74 6f 20 53 51 4c de is set to SQL
41680 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 ITE_LOCKED_SHARE
41690 44 43 41 43 48 45 2e 20 4f 74 68 65 72 77 69 73 DCACHE. Otherwis
416a0 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 73 70 65 e, in.** the spe
416b0 63 69 61 6c 20 22 44 52 4f 50 20 54 41 42 4c 45 cial "DROP TABLE
416c0 2f 49 4e 44 45 58 22 20 63 61 73 65 2c 20 74 68 /INDEX" case, th
416d0 65 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 e extended error
416e0 20 63 6f 64 65 20 69 73 20 6a 75 73 74 20 0a 2a code is just .*
416f0 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 2e * SQLITE_LOCKED.
41700 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
41710 6e 74 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 nt sqlite3_unloc
41720 6b 5f 6e 6f 74 69 66 79 28 0a 20 20 73 71 6c 69 k_notify(. sqli
41730 74 65 33 20 2a 70 42 6c 6f 63 6b 65 64 2c 20 20 te3 *pBlocked,
41740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41750 20 20 20 20 20 20 20 20 2f 2a 20 57 61 69 74 69 /* Waiti
41760 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f ng connection */
41770 0a 20 20 76 6f 69 64 20 28 2a 78 4e 6f 74 69 66 . void (*xNotif
41780 79 29 28 76 6f 69 64 20 2a 2a 61 70 41 72 67 2c y)(void **apArg,
41790 20 69 6e 74 20 6e 41 72 67 29 2c 20 20 20 20 2f int nArg), /
417a0 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * Callback funct
417b0 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 2a 2f ion to invoke */
417c0 0a 20 20 76 6f 69 64 20 2a 70 4e 6f 74 69 66 79 . void *pNotify
417d0 41 72 67 20 20 20 20 20 20 20 20 20 20 20 20 20 Arg
417e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
417f0 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 70 61 * Argument to pa
41800 73 73 20 74 6f 20 78 4e 6f 74 69 66 79 20 2a 2f ss to xNotify */
41810 0a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 .);.../*.** CAPI
41820 33 52 45 46 3a 20 53 74 72 69 6e 67 20 43 6f 6d 3REF: String Com
41830 70 61 72 69 73 6f 6e 0a 2a 2a 20 45 58 50 45 52 parison.** EXPER
41840 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
41850 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 e [sqlite3_strni
41860 63 6d 70 28 29 5d 20 41 50 49 20 61 6c 6c 6f 77 cmp()] API allow
41870 73 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 s applications a
41880 6e 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 6f nd extensions to
41890 0a 2a 2a 20 63 6f 6d 70 61 72 65 20 74 68 65 20 .** compare the
418a0 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 77 6f 20 contents of two
418b0 62 75 66 66 65 72 73 20 63 6f 6e 74 61 69 6e 69 buffers containi
418c0 6e 67 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 ng UTF-8 strings
418d0 20 69 6e 20 61 0a 2a 2a 20 63 61 73 65 2d 69 6e in a.** case-in
418e0 64 65 6e 64 65 6e 74 20 66 61 73 68 69 6f 6e 2c dendent fashion,
418f0 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 using the same
41900 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 63 61 definition of ca
41910 73 65 20 69 6e 64 65 70 65 6e 64 65 6e 63 65 20 se independence
41920 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 .** that SQLite
41930 75 73 65 73 20 69 6e 74 65 72 6e 61 6c 6c 79 20 uses internally
41940 77 68 65 6e 20 63 6f 6d 70 61 72 69 6e 67 20 69 when comparing i
41950 64 65 6e 74 69 66 69 65 72 73 2e 0a 2a 2f 0a 53 dentifiers..*/.S
41960 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
41970 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 63 lite3_strnicmp(c
41980 6f 6e 73 74 20 63 68 61 72 20 2a 2c 20 63 6f 6e onst char *, con
41990 73 74 20 63 68 61 72 20 2a 2c 20 69 6e 74 29 3b st char *, int);
419a0 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 65 ../*.** Undo the
419b0 20 68 61 63 6b 20 74 68 61 74 20 63 6f 6e 76 65 hack that conve
419c0 72 74 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 rts floating poi
419d0 6e 74 20 74 79 70 65 73 20 74 6f 20 69 6e 74 65 nt types to inte
419e0 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75 69 6c 64 ger for.** build
419f0 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f 72 73 20 s on processors
41a00 77 69 74 68 6f 75 74 20 66 6c 6f 61 74 69 6e 67 without floating
41a10 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2e 0a point support..
41a20 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
41a30 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 _OMIT_FLOATING_P
41a40 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20 64 6f 75 OINT.# undef dou
41a50 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 ble.#endif..#ifd
41a60 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 7d ef __cplusplus.}
41a70 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74 68 65 20 /* End of the
41a80 27 65 78 74 65 72 6e 20 22 43 22 27 20 62 6c 6f 'extern "C"' blo
41a90 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e ck */.#endif.#en
41aa0 64 69 66 0a 0a dif..