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 30 22 0a 23 64 65 66 69 "3.6.20".#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 30 N_NUMBER 3006020
1140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1150: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 SOURCE_ID "
1160: 32 30 30 39 2d 31 30 2d 33 30 20 31 34 3a 32 37 2009-10-30 14:27
1170: 3a 31 35 20 36 31 32 39 35 32 37 34 33 64 61 32 :15 612952743da2
1180: 38 65 36 35 31 35 31 32 35 34 37 66 63 30 64 33 8e651512547fc0d3
1190: 39 32 35 66 34 63 36 39 38 65 62 34 22 0a 0a 2f 925f4c698eb4"../
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 69 73 20 72 6f 75 74 69 6e 65 73 20 61 72 65 his routines are
8ef0: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 designed to aid
8f00: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 in process init
8f10: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a ialization and.*
8f20: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d * shutdown on em
8f30: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 bedded systems.
8f40: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 Workstation app
8f50: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a lications using.
8f60: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c ** SQLite normal
8f70: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 ly do not need t
8f80: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 o invoke either
8f90: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
8fa0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 s..**.** A call
8fb0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 to sqlite3_initi
8fc0: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 alize() is an "e
8fd0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 ffective" call i
8fe0: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 f it is.** the f
8ff0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 irst time sqlite
9000: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
9010: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 s invoked during
9020: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 the lifetime of
9030: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c .** the process,
9040: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 or if it is the
9050: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 first time sqli
9060: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9070: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 is invoked.** f
9080: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 ollowing a call
9090: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 to sqlite3_shutd
90a0: 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 own(). Only an
90b0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a effective call.*
90c0: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 * of sqlite3_ini
90d0: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 tialize() does a
90e0: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ny initializatio
90f0: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 n. All other ca
9100: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c lls.** are harml
9110: 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a ess no-ops..**.*
9120: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 * A call to sqli
9130: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 te3_shutdown() i
9140: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
9150: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 call if it is t
9160: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c he first.** call
9170: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
9180: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 down() since the
9190: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e last sqlite3_in
91a0: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 4f 6e 6c itialize(). Onl
91b0: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 y.** an effectiv
91c0: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 e call to sqlite
91d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 3_shutdown() doe
91e0: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 s any deinitiali
91f0: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f zation..** All o
9200: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 ther valid calls
9210: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
9220: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c down() are harml
9230: 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a ess no-ops..**.*
9240: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
9250: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 itialize() inter
9260: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 face is threadsa
9270: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f fe, but sqlite3_
9280: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 shutdown().** is
9290: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 not. The sqlit
92a0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e e3_shutdown() in
92b0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c terface must onl
92c0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d y be called from
92d0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 a.** single thr
92e0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b ead. All open [
92f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
9300: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c ions] must be cl
9310: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 osed and all.**
9320: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 other SQLite res
9330: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 ources must be d
9340: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 eallocated prior
9350: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 to invoking.**
9360: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
9370: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 ()..**.** Among
9380: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 other things, sq
9390: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
93a0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a () will invoke.*
93b0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
93c0: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c t(). Similarly,
93d0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
93e0: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f n().** will invo
93f0: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ke sqlite3_os_en
9400: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 d()..**.** The s
9410: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9420: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
9430: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
9440: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 on success..** I
9450: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f f for some reaso
9460: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 n, sqlite3_initi
9470: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c alize() is unabl
9480: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a e to initialize.
9490: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 ** the library (
94a0: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e perhaps it is un
94b0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
94c0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 a needed resour
94d0: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 ce such.** as a
94e0: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e mutex) it return
94f0: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 s an [error code
9500: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 ] other than [SQ
9510: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 LITE_OK]..**.**
9520: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
9530: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
9540: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 is called inter
9550: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 nally by many ot
9560: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
9570: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 terfaces so that
9580: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
9590: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 usually does not
95a0: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f need to.** invo
95b0: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ke sqlite3_initi
95c0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 alize() directly
95d0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 . For example,
95e0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
95f0: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 .** calls sqlite
9600: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 3_initialize() s
9610: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 o the SQLite lib
9620: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 rary will be aut
9630: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e omatically.** in
9640: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b itialized when [
9650: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 sqlite3_open()]
9660: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 is called if it
9670: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 has not be initi
9680: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 alized.** alread
9690: 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 y. However, if
96a0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
96b0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ed with the [SQL
96c0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
96d0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 T].** compile-ti
96e0: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 me option, then
96f0: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 the automatic ca
9700: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 lls to sqlite3_i
9710: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 nitialize().** a
9720: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 re omitted and t
9730: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
9740: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 ust call sqlite3
9750: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 _initialize() di
9760: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 rectly.** prior
9770: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
9780: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
9790: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 ace. For maximu
97a0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a m portability,.*
97b0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * it is recommen
97c0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
97d0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 tions always inv
97e0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
97f0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 ialize().** dire
9800: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 ctly prior to us
9810: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
9820: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
9830: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 Future releases
9840: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 .** of SQLite ma
9850: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 y require this.
9860: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
9870: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 the behavior ex
9880: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 hibited.** when
9890: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
98a0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
98b0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d OMIT_AUTOINIT] m
98c0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a ight become the.
98d0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 ** default behav
98e0: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ior in some futu
98f0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 re release of SQ
9900: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
9910: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
9920: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f ) routine does o
9930: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
9940: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 specific.** init
9950: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 ialization of th
9960: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
9970: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f . The sqlite3_o
9980: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 s_end().** routi
9990: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 ne undoes the ef
99a0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f fect of sqlite3_
99b0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 os_init(). Typi
99c0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 cal tasks.** per
99d0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 formed by these
99e0: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 routines include
99f0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 allocation or d
9a00: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
9a10: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 f static resourc
9a20: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 es, initializati
9a30: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 on of global var
9a40: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 iables,.** setti
9a50: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 ng up a default
9a60: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f [sqlite3_vfs] mo
9a70: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 dule, or setting
9a80: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 up.** a default
9a90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 configuration u
9aa0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f sing [sqlite3_co
9ab0: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 nfig()]..**.** T
9ac0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
9ad0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f hould never invo
9ae0: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 ke either sqlite
9af0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 3_os_init().** o
9b00: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
9b10: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 () directly. Th
9b20: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
9b30: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 ould only invoke
9b40: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 .** sqlite3_init
9b50: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c ialize() and sql
9b60: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
9b70: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 The sqlite3_os
9b80: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 _init().** inter
9b90: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 face is called a
9ba0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
9bb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9bc0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 ze() and.** sqli
9bd0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 te3_os_end() is
9be0: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 called by sqlite
9bf0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 3_shutdown(). A
9c00: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d ppropriate.** im
9c10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
9c20: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 r sqlite3_os_ini
9c30: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
9c40: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 os_end().** are
9c50: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
9c60: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d e when it is com
9c70: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 piled for Unix,
9c80: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 Windows, or OS/2
9c90: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f ..** When [custo
9ca0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 m builds | built
9cb0: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 for other platf
9cc0: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 orms].** (using
9cd0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f the [SQLITE_OS_O
9ce0: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d THER=1] compile-
9cf0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 time.** option)
9d00: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
9d10: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 must supply a su
9d20: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 itable implement
9d30: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c ation for.** sql
9d40: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
9d50: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
9d60: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 d(). An applica
9d70: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a tion-supplied.**
9d80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
9d90: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
9da0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f it() or sqlite3_
9db0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 os_end().** must
9dc0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
9dd0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 OK] on success a
9de0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 nd some other [e
9df0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a rror code] upon.
9e00: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 ** failure..*/.S
9e10: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
9e20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9e30: 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 (void);.SQLITE_A
9e40: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 PI int sqlite3_s
9e50: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 hutdown(void);.S
9e60: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
9e70: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f lite3_os_init(vo
9e80: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
9e90: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 int sqlite3_os_e
9ea0: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a nd(void);../*.**
9eb0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
9ec0: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 guring The SQLit
9ed0: 65 20 4c 69 62 72 61 72 79 20 7b 48 31 34 31 30 e Library {H1410
9ee0: 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 32 0} <S20000><S302
9ef0: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
9f00: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 TAL.**.** The sq
9f10: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
9f20: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
9f30: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 to make global
9f40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
9f50: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 changes to SQLi
9f60: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 te in order to t
9f70: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 une SQLite to th
9f80: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
9f90: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
9fa0: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 cation. The def
9fb0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
9fc0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 on is recommende
9fd0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 d for most.** ap
9fe0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 plications and s
9ff0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 o this routine i
a000: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 s usually not ne
a010: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a cessary. It is.
a020: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 ** provided to s
a030: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c upport rare appl
a040: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e ications with un
a050: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a usual needs..**.
a060: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
a070: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
a080: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 e is not threads
a090: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 afe. The applic
a0a0: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e ation.** must in
a0b0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 sure that no oth
a0c0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
a0d0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 aces are invoked
a0e0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 by other.** thr
a0f0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 eads while sqlit
a100: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 e3_config() is r
a110: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 unning. Further
a120: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f more, sqlite3_co
a130: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e nfig().** may on
a140: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 ly be invoked pr
a150: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 ior to library i
a160: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 nitialization us
a170: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
a180: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 initialize()] or
a190: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 after shutdown
a1a0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 by [sqlite3_shut
a1b0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 down()]..** Note
a1c0: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 , however, that
a1d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
a1e0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 can be called a
a1f0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a s part of the.**
a200: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
a210: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f of an applicatio
a220: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 n-defined [sqlit
a230: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a e3_os_init()]..*
a240: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
a250: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
a260: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 e3_config() is a
a270: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 n integer.** [SQ
a280: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
a290: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 LETHREAD | confi
a2a0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d guration option]
a2b0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 that determines
a2c0: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 .** what propert
a2d0: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 y of SQLite is t
a2e0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e o be configured.
a2f0: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 Subsequent arg
a300: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 uments.** vary d
a310: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
a320: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
a330: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f INGLETHREAD | co
a340: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
a350: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 on].** in the fi
a360: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
a370: 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69 .** When a confi
a380: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
a390: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f is set, sqlite3_
a3a0: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 config() returns
a3b0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
a3c0: 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 If the option i
a3d0: 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c s unknown or SQL
a3e0: 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
a3f0: 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a set the option.
a400: 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 ** then this rou
a410: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e tine returns a n
a420: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
a430: 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ode]..**.** Requ
a440: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
a450: 34 31 30 33 5d 20 5b 48 31 34 31 30 36 5d 20 5b 4103] [H14106] [
a460: 48 31 34 31 32 30 5d 20 5b 48 31 34 31 32 33 5d H14120] [H14123]
a470: 20 5b 48 31 34 31 32 36 5d 20 5b 48 31 34 31 32 [H14126] [H1412
a480: 39 5d 20 5b 48 31 34 31 33 32 5d 20 5b 48 31 34 9] [H14132] [H14
a490: 31 33 35 5d 0a 2a 2a 20 5b 48 31 34 31 33 38 5d 135].** [H14138]
a4a0: 20 5b 48 31 34 31 34 31 5d 20 5b 48 31 34 31 34 [H14141] [H1414
a4b0: 34 5d 20 5b 48 31 34 31 34 37 5d 20 5b 48 31 34 4] [H14147] [H14
a4c0: 31 35 30 5d 20 5b 48 31 34 31 35 33 5d 20 5b 48 150] [H14153] [H
a4d0: 31 34 31 35 36 5d 20 5b 48 31 34 31 35 39 5d 0a 14156] [H14159].
a4e0: 2a 2a 20 5b 48 31 34 31 36 32 5d 20 5b 48 31 34 ** [H14162] [H14
a4f0: 31 36 35 5d 20 5b 48 31 34 31 36 38 5d 0a 2a 2f 165] [H14168].*/
a500: 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
a510: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
a520: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 int sqlite3_conf
a530: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f ig(int, ...);../
a540: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
a550: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 onfigure databas
a560: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b e connections {
a570: 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30 30 3e H14200} <S20000>
a580: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
a590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
a5a0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 e3_db_config() i
a5b0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
a5c0: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 to make configu
a5d0: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 ration.** change
a5e0: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 s to a [database
a5f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 connection]. T
a600: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 he interface is
a610: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 similar to.** [s
a620: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
a630: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 except that the
a640: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 changes apply t
a650: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 o a single.** [d
a660: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
a670: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 on] (specified i
a680: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
a690: 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 ment). The.** s
a6a0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
a6b0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e () interface can
a6c0: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d only be used im
a6d0: 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a mediately after.
a6e0: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
a6f0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 connection is cr
a700: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c eated using [sql
a710: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a ite3_open()],.**
a720: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
a730: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 ()], or [sqlite3
a740: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a _open_v2()]. .*
a750: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
a760: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
a770: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c te3_db_config(D,
a780: 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a V,...) is the.*
a790: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
a7a0: 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 verb - an intege
a7b0: 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 r code that indi
a7c0: 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 cates what.** as
a7d0: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 pect of the [dat
a7e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
a7f0: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 ] is being confi
a800: 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e gured..** The on
a810: 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 ly choice for th
a820: 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c is value is [SQL
a830: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
a840: 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 KASIDE]..** New
a850: 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 verbs are likely
a860: 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 to be added in
a870: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
a880: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 of SQLite..** Ad
a890: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
a8a0: 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 ts depend on the
a8b0: 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 verb..**.** Req
a8c0: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
a8d0: 31 34 32 30 33 5d 20 5b 48 31 34 32 30 36 5d 20 14203] [H14206]
a8e0: 5b 48 31 34 32 30 39 5d 20 5b 48 31 34 32 31 32 [H14209] [H14212
a8f0: 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f 0a 53 51 ] [H14215].*/.SQ
a900: 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
a910: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
a920: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
a930: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ig(sqlite3*, int
a940: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a op, ...);../*.*
a950: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
a960: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f ry Allocation Ro
a970: 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 utines {H10155}
a980: 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 <S20120>.** EXPE
a990: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 RIMENTAL.**.** A
a9a0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
a9b0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 is object define
a9c0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
a9d0: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a between SQLite.*
a9e0: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 * and low-level
a9f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
aa00: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a n routines..**.*
aa10: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
aa20: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e used in only on
aa30: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 e place in the S
aa40: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
aa50: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
aa60: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
aa70: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 this object is t
aa80: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a he argument to.*
aa90: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
aaa0: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f g()] when the co
aab0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
aac0: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 on is.** [SQLITE
aad0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 _CONFIG_MALLOC]
aae0: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
aaf0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a G_GETMALLOC]. .
ab00: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 ** By creating a
ab10: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
ab20: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 is object.** and
ab30: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
ab40: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
ab50: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
ab60: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e ALLOC]).** durin
ab70: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c g configuration,
ab80: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
ab90: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 can specify an a
aba0: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
abb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
abc0: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 subsystem for SQ
abd0: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 Lite to use for
abe0: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 all of its.** dy
abf0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 namic memory nee
ac00: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 ds..**.** Note t
ac10: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 hat SQLite comes
ac20: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 with several [b
ac30: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
ac40: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 llocators].** th
ac50: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 at are perfectly
ac60: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 adequate for th
ac70: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d e overwhelming m
ac80: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 ajority of appli
ac90: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 cations.** and t
aca0: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 hat this object
acb0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 is only useful t
acc0: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 o a tiny minorit
acd0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
ace0: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 s.** with specia
acf0: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c lized memory all
ad00: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d ocation requirem
ad10: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 ents. This obje
ad20: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 ct is.** also us
ad30: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
ad40: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f g of SQLite in o
ad50: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 rder to specify
ad60: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
ad70: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
ad80: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 or that simulate
ad90: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d s memory out-of-
ada0: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e memory condition
adb0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f s in.** order to
adc0: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c verify that SQL
add0: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 ite recovers gra
ade0: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 cefully from suc
adf0: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e h.** conditions.
ae00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c .**.** The xMall
ae10: 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 oc and xFree met
ae20: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c hods must work l
ae30: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f ike the.** mallo
ae40: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
ae50: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 unctions from th
ae60: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
ae70: 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 rary..** The xRe
ae80: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 alloc method mus
ae90: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c t work like real
aea0: 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 loc() from the s
aeb0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
aec0: 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 y.** with the ex
aed0: 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 ception that if
aee0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
aef0: 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 ent to xRealloc
af00: 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 is zero,.** xRea
af10: 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e lloc must be a n
af20: 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e o-op - it must n
af30: 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 ot perform any a
af40: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 llocation or.**
af50: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 53 deallocation. S
af60: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 64 QLite guaranteed
af70: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e s that the secon
af80: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
af90: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 xRealloc is alw
afa0: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 ays a value retu
afb0: 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 rned by a prior
afc0: 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 call to xRoundup
afd0: 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 ..** And so in c
afe0: 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e ases where xRoun
aff0: 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 dup always retur
b000: 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 ns a positive nu
b010: 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f mber,.** xReallo
b020: 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 c can perform ex
b030: 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 actly as the sta
b040: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 ndard library re
b050: 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 alloc() and.** s
b060: 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c till be in compl
b070: 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 iance with this
b080: 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a specification..*
b090: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c *.** xSize shoul
b0a0: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c d return the all
b0b0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 ocated size of a
b0c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
b0d0: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 on.** previously
b0e0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 obtained from x
b0f0: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c Malloc or xReall
b100: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 oc. The allocat
b110: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c ed size.** is al
b120: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 ways at least as
b130: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 big as the requ
b140: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d ested size but m
b150: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a ay be larger..**
b160: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 .** The xRoundup
b170: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
b180: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 what would be th
b190: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
b1a0: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 of.** a memory
b1b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e allocation given
b1c0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
b1d0: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d quested size. M
b1e0: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ost memory.** al
b1f0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 locators round u
b200: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 p memory allocat
b210: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f ions at least to
b220: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 the next multip
b230: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d le.** of 8. Som
b240: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 e allocators rou
b250: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 nd up to a large
b260: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f r multiple or to
b270: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a a power of 2..*
b280: 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 * Every memory a
b290: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 llocation reques
b2a0: 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f t coming in thro
b2b0: 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c ugh [sqlite3_mal
b2c0: 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 loc()].** or [sq
b2d0: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
b2e0: 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f first calls xRo
b2f0: 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e undup. If xRoun
b300: 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a dup returns 0, .
b310: 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 ** that causes t
b320: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
b330: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
b340: 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a on to fail..**.*
b350: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 * The xInit meth
b360: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 od initializes t
b370: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
b380: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 tor. (For examp
b390: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 le,.** it might
b3a0: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 allocate any req
b3b0: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 uire mutexes or
b3c0: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 initialize inter
b3d0: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 nal data.** stru
b3e0: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 ctures. The xSh
b3f0: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 utdown method is
b400: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 invoked (indire
b410: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c ctly) by.** [sql
b420: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
b430: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c and should deal
b440: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 locate any resou
b450: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a rces acquired.**
b460: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 by xInit. The
b470: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 pAppData pointer
b480: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
b490: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 only parameter t
b4a0: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 o.** xInit and x
b4b0: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 Shutdown..**.**
b4c0: 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 SQLite holds the
b4d0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 [SQLITE_MUTEX_S
b4e0: 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 TATIC_MASTER] mu
b4f0: 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f tex when it invo
b500: 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 kes.** the xInit
b510: 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 method, so the
b520: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 xInit method nee
b530: 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 d not be threads
b540: 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 afe. The.** xSh
b550: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 utdown method is
b560: 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f only called fro
b570: 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 m [sqlite3_shutd
b580: 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 own()] so it doe
b590: 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f s.** not need to
b5a0: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 be threadsafe e
b5b0: 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 ither. For all
b5c0: 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 other methods, S
b5d0: 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 QLite.** holds t
b5e0: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 he [SQLITE_MUTEX
b5f0: 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 _STATIC_MEM] mut
b600: 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 ex as long as th
b610: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e.** [SQLITE_CON
b620: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 FIG_MEMSTATUS] c
b630: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
b640: 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e ion is turned on
b650: 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 (which.** it is
b660: 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 by default) and
b670: 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 so the methods
b680: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c are automaticall
b690: 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a y serialized..**
b6a0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 However, if [SQ
b6b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
b6c0: 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c TATUS] is disabl
b6d0: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 ed, then the oth
b6e0: 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 er.** methods mu
b6f0: 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 st be threadsafe
b700: 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 or else make th
b710: 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d eir own arrangem
b720: 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 ents for.** seri
b730: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a alization..**.**
b740: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 SQLite will nev
b750: 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 er invoke xInit(
b760: 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 ) more than once
b770: 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 without an inte
b780: 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 rvening.** call
b790: 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a to xShutdown()..
b7a0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
b7b0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
b7c0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 thods sqlite3_me
b7d0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 m_methods;.struc
b7e0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
b7f0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a thods {. void *
b800: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b (*xMalloc)(int);
b810: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f /* Memo
b820: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 ry allocation fu
b830: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 nction */. void
b840: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 (*xFree)(void*)
b850: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 ; /* Fr
b860: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 ee a prior alloc
b870: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ation */. void
b880: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 *(*xRealloc)(voi
b890: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 d*,int); /* Res
b8a0: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f ize an allocatio
b8b0: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 n */. int (*xSi
b8c0: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ze)(void*);
b8d0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 /* Return
b8e0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 the size of an a
b8f0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 llocation */. i
b900: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 nt (*xRoundup)(i
b910: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a nt); /*
b920: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 Round up reques
b930: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 t size to alloca
b940: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 tion size */. i
b950: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 nt (*xInit)(void
b960: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a *); /*
b970: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 Initialize the
b980: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
b990: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 */. void (*xSh
b9a0: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 utdown)(void*);
b9b0: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 /* Deinitia
b9c0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
b9d0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
b9e0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 oid *pAppData;
b9f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
ba00: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e Argument to xIn
ba10: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f it() and xShutdo
ba20: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a wn() */.};../*.*
ba30: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
ba40: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
ba50: 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 s {H10160} <S200
ba60: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
ba70: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TAL.**.** These
ba80: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
ba90: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
baa0: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ger configuratio
bab0: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a n options that.*
bac0: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 * can be passed
bad0: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
bae0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
baf0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
bb00: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
bb10: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
bb20: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
bb30: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
bb40: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
bb50: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
bb60: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
bb70: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
bb80: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
bb90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
bba0: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
bbb0: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
bbc0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 m [sqlite3_confi
bbd0: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 g()] to make sur
bbe0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 e that.** the ca
bbf0: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 ll worked. The
bc00: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
bc10: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c )] interface wil
bc20: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f l return a.** no
bc30: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
bc40: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 de] if a discont
bc50: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f inued or unsuppo
bc60: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 rted configurati
bc70: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 on option.** is
bc80: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c invoked..**.** <
bc90: 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 dl>.** <dt>SQLIT
bca0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
bcb0: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 HREAD</dt>.** <d
bcc0: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
bcd0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
bce0: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f option. This o
bcf0: 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a ption disables.*
bd00: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 * all mutexing a
bd10: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 nd puts SQLite i
bd20: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 nto a mode where
bd30: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 it can only be
bd40: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e used.** by a sin
bd50: 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e gle thread.</dd>
bd60: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
bd70: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
bd80: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
bd90: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
bda0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
bdb0: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 option. This op
bdc0: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a tion disables.**
bdd0: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 mutexing on [da
bde0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
bdf0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
be00: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
be10: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c cts..** The appl
be20: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f ication is respo
be30: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 nsible for seria
be40: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f lizing access to
be50: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
be60: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b nnections] and [
be70: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
be80: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 nts]. But other
be90: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 mutexes.** are
bea0: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 enabled so that
beb0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 SQLite will be s
bec0: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 afe to use in a
bed0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a multi-threaded.*
bee0: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 * environment as
bef0: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 long as no two
bf00: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 threads attempt
bf10: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a to use the same.
bf20: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
bf30: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 nection] at the
bf40: 73 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20 same time. See
bf50: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d the [threading m
bf60: 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 ode].** document
bf70: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
bf80: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
bf90: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
bfa0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
bfb0: 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a ERIALIZED</dt>.*
bfc0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
bfd0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
bfe0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 this option. Th
bff0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 is option enable
c000: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 s.** all mutexes
c010: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 including the r
c020: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 ecursive.** mute
c030: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 xes on [database
c040: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
c050: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
c060: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
c070: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 * In this mode (
c080: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 which is the def
c090: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 ault when SQLite
c0a0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
c0b0: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 h.** [SQLITE_THR
c0c0: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 EADSAFE=1]) the
c0d0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
c0e0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 ill itself seria
c0f0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 lize access.** t
c100: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e o [database conn
c110: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
c120: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
c130: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a s] so that the.*
c140: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 * application is
c150: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 free to use the
c160: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
c170: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 connection] or t
c180: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 he.** same [prep
c190: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
c1a0: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 in different thr
c1b0: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
c1c0: 20 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 time..** See th
c1d0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
c1e0: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e e] documentation
c1f0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
c200: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 information.</dd
c210: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
c220: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
c230: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
c240: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
c250: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
c260: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
c270: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 ter to an.** ins
c280: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
c290: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
c2a0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
c2b0: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 he argument spec
c2c0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 ifies.** alterna
c2d0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
c2e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
c2f0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
c300: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 used in place of
c310: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 .** the memory a
c320: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
c330: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 es built into SQ
c340: 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a Lite.</dd>.**.**
c350: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
c360: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 IG_GETMALLOC</dt
c370: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
c380: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
c390: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
c3a0: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ch is a pointer
c3b0: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 to an.** instanc
c3c0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
c3d0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 3_mem_methods] s
c3e0: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b tructure. The [
c3f0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
c400: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ods].** structur
c410: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 e is filled with
c420: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 the currently d
c430: 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c efined memory al
c440: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
c450: 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f s..** This optio
c460: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
c470: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 overload the de
c480: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c fault memory all
c490: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 ocation.** routi
c4a0: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 nes with a wrapp
c4b0: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 er that simulati
c4c0: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ons memory alloc
c4d0: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 ation failure or
c4e0: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 .** tracks memor
c4f0: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 y usage, for exa
c500: 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a mple.</dd>.**.**
c510: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
c520: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 IG_MEMSTATUS</dt
c530: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
c540: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c tion takes singl
c550: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 e argument of ty
c560: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 pe int, interpre
c570: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f ted as a .** boo
c580: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 lean, which enab
c590: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
c5a0: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f the collection o
c5b0: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 f memory allocat
c5c0: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 ion .** statisti
c5d0: 63 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65 cs. When disable
c5e0: 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 d, the following
c5f0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
c600: 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f es become .** no
c610: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a n-operational:.*
c620: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c * <ul>.** <l
c630: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
c640: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 ry_used()].**
c650: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
c660: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
c670: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
c680: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
c690: 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 imit()].** <li
c6a0: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 > [sqlite3_statu
c6b0: 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a s()].** </ul>.
c6c0: 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ** </dd>.**.** <
c6d0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
c6e0: 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a _SCRATCH</dt>.**
c6f0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
c700: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
c710: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
c720: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 r that SQLite ca
c730: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 n use for.** scr
c740: 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 atch memory. Th
c750: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
c760: 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e guments: A poin
c770: 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a ter an 8-byte.**
c780: 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 aligned memory
c790: 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 buffer from whic
c7a0: 68 20 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c h the scrach all
c7b0: 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 ocations will be
c7c0: 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 .** drawn, the s
c7d0: 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 ize of each scra
c7e0: 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 tch allocation (
c7f0: 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 sz),.** and the
c800: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
c810: 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 f scratch alloca
c820: 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 tions (N). The
c830: 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d sz.** argument m
c840: 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c ust be a multipl
c850: 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 e of 16. The sz
c860: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 parameter should
c870: 20 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a be a few bytes.
c880: 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 ** larger than t
c890: 68 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 he actual scratc
c8a0: 68 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 h space required
c8b0: 20 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c due to internal
c8c0: 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 overhead..** Th
c8d0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
c8e0: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 should pointer
c8f0: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 to an 8-byte ali
c900: 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f gned buffer.** o
c910: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
c920: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e bytes of memory.
c930: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
c940: 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e use no more than
c950: 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 one scratch buf
c960: 66 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 fer at once per
c970: 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 thread, so.** N
c980: 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f should be set to
c990: 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 the expected ma
c9a0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
c9b0: 74 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a threads. The sz
c9c0: 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 .** parameter sh
c9d0: 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 ould be 6 times
c9e0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
c9f0: 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 largest database
ca00: 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 page size..** S
ca10: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61 cratch buffers a
ca20: 72 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20 re used as part
ca30: 6f 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c of the btree bal
ca40: 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 ance operation.
ca50: 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 If.** The btree
ca60: 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 balancer needs
ca70: 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 additional memor
ca80: 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 y beyond what is
ca90: 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 provided by.**
caa0: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 scratch buffers
cab0: 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 or if no scratch
cac0: 20 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73 buffer space is
cad0: 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e specified, then
cae0: 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 SQLite.** goes
caf0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
cb00: 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 oc()] to obtain
cb10: 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 the memory it ne
cb20: 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 eds.</dd>.**.**
cb30: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
cb40: 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e G_PAGECACHE</dt>
cb50: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
cb60: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
cb70: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
cb80: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
cb90: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 can use for.**
cba0: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
cbb0: 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 e cache with the
cbc0: 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 default page ca
cbd0: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f che implemenatio
cbe0: 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e n. .** This con
cbf0: 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c figuration shoul
cc00: 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 d not be used if
cc10: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
cc20: 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 define page.** c
cc30: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
cc40: 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 ion is loaded us
cc50: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ing the SQLITE_C
cc60: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 ONFIG_PCACHE opt
cc70: 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 ion..** There ar
cc80: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
cc90: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
cca0: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 : A pointer to 8
ccb0: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a -byte aligned.**
ccc0: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a memory, the siz
ccd0: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 e of each page b
cce0: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 uffer (sz), and
ccf0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 the number of pa
cd00: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 ges (N)..** The
cd10: 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 sz argument shou
cd20: 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f ld be the size o
cd30: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 f the largest da
cd40: 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 tabase page.** (
cd50: 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 a power of two b
cd60: 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 etween 512 and 3
cd70: 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 2768) plus a lit
cd80: 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 tle extra for ea
cd90: 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 ch.** page heade
cda0: 72 2e 20 20 54 68 65 20 70 61 67 65 20 68 65 61 r. The page hea
cdb0: 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 der size is 20 t
cdc0: 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e o 40 bytes depen
cdd0: 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 ding on.** the h
cde0: 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 ost architecture
cdf0: 2e 20 20 49 74 20 69 73 20 68 61 72 6d 6c 65 73 . It is harmles
ce00: 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 s, apart from th
ce10: 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c e wasted memory,
ce20: 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 .** to make sz a
ce30: 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 little too larg
ce40: 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a e. The first.**
ce50: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
ce60: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c point to an all
ce70: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 ocation of at le
ce80: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
ce90: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c f memory..** SQL
cea0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 ite will use the
ceb0: 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 memory provided
cec0: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 by the first ar
ced0: 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 gument to satisf
cee0: 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 y its.** memory
cef0: 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 needs for the fi
cf00: 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 rst N pages that
cf10: 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 it adds to cach
cf20: 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 e. If additiona
cf30: 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 l.** page cache
cf40: 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 memory is needed
cf50: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 beyond what is
cf60: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 provided by this
cf70: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a option, then.**
cf80: 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 SQLite goes to
cf90: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
cfa0: 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 )] for the addit
cfb0: 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 ional storage sp
cfc0: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c ace..** The impl
cfd0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 ementation might
cfe0: 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 use one or more
cff0: 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 of the N buffer
d000: 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 s to hold .** me
d010: 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 mory accounting
d020: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 information. The
d030: 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 pointer in the
d040: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
d050: 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 ust.** be aligne
d060: 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 d to an 8-byte b
d070: 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 oundary or subse
d080: 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f quent behavior o
d090: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c f SQLite.** will
d0a0: 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f be undefined.</
d0b0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
d0c0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
d0d0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
d0e0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 s option specifi
d0f0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
d100: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 ry buffer that S
d110: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
d120: 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 * for all of its
d130: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 dynamic memory
d140: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
d150: 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 beyond those pr
d160: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 ovided.** for by
d170: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
d180: 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 SCRATCH] and [SQ
d190: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
d1a0: 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 CACHE]..** There
d1b0: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d are three argum
d1c0: 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 ents: An 8-byte
d1d0: 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 aligned pointer
d1e0: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a to the memory,.*
d1f0: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
d200: 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d bytes in the mem
d210: 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 ory buffer, and
d220: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f the minimum allo
d230: 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 cation size..**
d240: 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 If the first poi
d250: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
d260: 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c pointer) is NUL
d270: 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 L, then SQLite r
d280: 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 everts.** to usi
d290: 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d ng its default m
d2a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
d2b0: 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c (the system mall
d2c0: 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 oc() implementat
d2d0: 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 ion),.** undoing
d2e0: 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 any prior invoc
d2f0: 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 ation of [SQLITE
d300: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e _CONFIG_MALLOC].
d310: 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f If the.** memo
d320: 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f ry pointer is no
d330: 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 t NULL and eithe
d340: 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 r [SQLITE_ENABLE
d350: 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 _MEMSYS3] or.**
d360: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
d370: 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 EMSYS5] are defi
d380: 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c ned, then the al
d390: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 ternative memory
d3a0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 .** allocator is
d3b0: 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 engaged to hand
d3c0: 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 le all of SQLite
d3d0: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
d3e0: 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 ion needs..** Th
d3f0: 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
d400: 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
d410: 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 ter) must be ali
d420: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
d430: 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 e.** boundary or
d440: 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 subsequent beha
d450: 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 vior of SQLite w
d460: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 ill be undefined
d470: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
d480: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
d490: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
d4a0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
d4b0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
d4c0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
d4d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
d4e0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
d4f0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
d500: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
d510: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e re. The argumen
d520: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 t specifies.** a
d530: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c lternative low-l
d540: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 evel mutex routi
d550: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 nes to be used i
d560: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d n place.** the m
d570: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 utex routines bu
d580: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
d590: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
d5a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
d5b0: 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c TMUTEX</dt>.** <
d5c0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 dd>This option t
d5d0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
d5e0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
d5f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
d600: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
d610: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
d620: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
d630: 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 ture. The.** [s
d640: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
d650: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 hods].** structu
d660: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 re is filled wit
d670: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 h the currently
d680: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f defined mutex ro
d690: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 utines..** This
d6a0: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
d6b0: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
d6c0: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 he default mutex
d6d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
d6e0: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
d6f0: 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 rapper used to t
d700: 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 rack mutex usage
d710: 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 for performance
d720: 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 .** profiling or
d730: 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 testing, for ex
d740: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ample.</dd>.**.*
d750: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
d760: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 FIG_LOOKASIDE</d
d770: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
d780: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 ption takes two
d790: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
d7a0: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 etermine the def
d7b0: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 ault.** memory a
d7c0: 6c 6c 6f 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 llocation lookas
d7d0: 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ide optimization
d7e0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 . The first arg
d7f0: 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 ument is the.**
d800: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f size of each loo
d810: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c kaside buffer sl
d820: 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ot and the secon
d830: 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 d is the number
d840: 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f of.** slots allo
d850: 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 cated to each da
d860: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
d870: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 n. This option
d880: 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 sets the.** <i>d
d890: 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 efault</i> looka
d8a0: 73 69 64 65 20 73 69 7a 65 2e 20 20 54 68 65 20 side size. The
d8b0: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 [SQLITE_DBCONFIG
d8c0: 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 _LOOKASIDE].** v
d8d0: 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f erb to [sqlite3_
d8e0: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e db_config()] can
d8f0: 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e be used to chan
d900: 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 ge the lookaside
d910: 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
d920: 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 n on individual
d930: 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 3c 2f 64 64 connections.</dd
d940: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
d950: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
d960: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
d970: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
d980: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
d990: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
d9a0: 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 ter to.** an [sq
d9b0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
d9c0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 hods] object. T
d9d0: 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 his object speci
d9e0: 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 fies the interfa
d9f0: 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f ce.** to a custo
da00: 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 m page cache imp
da10: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51 lementation. SQ
da20: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 Lite makes a cop
da30: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 y of the.** obje
da40: 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 ct and uses it f
da50: 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 or page cache me
da60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
da70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
da80: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
da90: 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a ETPCACHE</dt>.**
daa0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
dab0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
dac0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
dad0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
dae0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 n.** [sqlite3_pc
daf0: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 ache_methods] ob
db00: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f ject. SQLite co
db10: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 pies of the curr
db20: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 ent.** page cach
db30: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
db40: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 into that objec
db50: 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f t.</dd>.**.** </
db60: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
db70: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
db80: 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a GLETHREAD 1 /*
db90: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nil */.#define
dba0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
dbb0: 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f LTITHREAD 2 /
dbc0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
dbd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
dbe0: 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 ERIALIZED 3
dbf0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
dc00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
dc10: 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 MALLOC 4
dc20: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f /* sqlite3_mem_
dc30: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
dc40: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
dc50: 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 G_GETMALLOC
dc60: 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 5 /* sqlite3_me
dc70: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
dc80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
dc90: 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 FIG_SCRATCH
dca0: 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6 /* void*, i
dcb0: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a nt sz, int N */.
dcc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
dcd0: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 ONFIG_PAGECACHE
dce0: 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 7 /* void*,
dcf0: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a int sz, int N *
dd00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
dd10: 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 _CONFIG_HEAP
dd20: 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 8 /* void
dd30: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e *, int nByte, in
dd40: 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 t min */.#define
dd50: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
dd60: 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 EMSTATUS 9
dd70: 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 /* boolean */.#d
dd80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
dd90: 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 FIG_MUTEX
dda0: 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 10 /* sqlite3_
ddb0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a mutex_methods* *
ddc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
ddd0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
dde0: 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 11 /* sqli
ddf0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
de00: 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 s* */./* previou
de10: 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 sly SQLITE_CONFI
de20: 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 G_CHUNKALLOC 12
de30: 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 which is now unu
de40: 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 sed. */ .#define
de50: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
de60: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 OOKASIDE 13
de70: 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 /* int int */.#d
de80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
de90: 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 FIG_PCACHE
dea0: 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 14 /* sqlite3_
deb0: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 pcache_methods*
dec0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
ded0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
dee0: 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c HE 15 /* sql
def0: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
df00: 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 ods* */../*.** C
df10: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
df20: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b ration Options {
df30: 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e H10170} <S20000>
df40: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
df50: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
df60: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 stants are the a
df70: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 vailable integer
df80: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
df90: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 ptions that.** c
dfa0: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 an be passed as
dfb0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
dfc0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
dfd0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
dfe0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
dff0: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 * New configurat
e000: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 ion options may
e010: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
e020: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
e030: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 QLite..** Existi
e040: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
e050: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 options might b
e060: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 e discontinued.
e070: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a Applications.**
e080: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 should check th
e090: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 e return code fr
e0a0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 om [sqlite3_db_c
e0b0: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 onfig()] to make
e0c0: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 sure that.** th
e0d0: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 e call worked.
e0e0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f The [sqlite3_db_
e0f0: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
e100: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
e110: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
e120: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
e130: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
e140: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
e150: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
e160: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
e170: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
e180: 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
e190: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
e1a0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
e1b0: 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 ion takes three
e1c0: 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
e1d0: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
e1e0: 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f ine the .** [loo
e1f0: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c kaside memory al
e200: 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 locator] configu
e210: 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b ration for the [
e220: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
e230: 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ion]..** The fir
e240: 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 st argument (the
e250: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
e260: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f to [sqlite3_db_
e270: 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a config()] is a.*
e280: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 * pointer to an
e290: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f memory buffer to
e2a0: 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 use for lookasi
e2b0: 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 54 68 de memory..** Th
e2c0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
e2d0: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 may be NULL in
e2e0: 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 which case SQLit
e2f0: 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 e will allocate
e300: 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 the.** lookaside
e310: 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 buffer itself u
e320: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 sing [sqlite3_ma
e330: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 lloc()]. The se
e340: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
e350: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 the.** size of
e360: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 each lookaside b
e370: 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 uffer slot and t
e380: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
e390: 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 t is the number
e3a0: 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 of.** slots. Th
e3b0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 e size of the bu
e3c0: 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 ffer in the firs
e3d0: 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 t argument must
e3e0: 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a be greater than.
e3f0: 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 ** or equal to t
e400: 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 he product of th
e410: 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 e second and thi
e420: 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 rd arguments. T
e430: 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 he buffer.** mus
e440: 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 t be aligned to
e450: 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 an 8-byte bounda
e460: 72 79 2e 20 20 49 66 20 74 68 65 20 73 65 63 6f ry. If the seco
e470: 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e nd argument is n
e480: 6f 74 0a 2a 2a 20 61 20 6d 75 6c 74 69 70 6c 65 ot.** a multiple
e490: 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 of 8, it is int
e4a0: 65 72 6e 61 6c 6c 79 20 72 6f 75 6e 64 65 64 20 ernally rounded
e4b0: 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 down to the next
e4c0: 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 smaller.** mult
e4d0: 69 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20 iple of 8. See
e4e0: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f also: [SQLITE_CO
e4f0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c NFIG_LOOKASIDE]<
e500: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
e510: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
e520: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
e530: 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f ASIDE 1001 /
e540: 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 * void* int int
e550: 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */.../*.** CAPI3
e560: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
e570: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 isable Extended
e580: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 Result Codes {H1
e590: 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2200} <S10700>.*
e5a0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
e5b0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
e5c0: 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 _codes() routine
e5d0: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
e5e0: 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 bles the.** [ext
e5f0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
e600: 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 es] feature of S
e610: 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e QLite. The exten
e620: 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ded result.** co
e630: 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 des are disabled
e640: 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 by default for
e650: 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 historical compa
e660: 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 tibility conside
e670: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 rations..**.** R
e680: 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
e690: 5b 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 [H12201] [H12202
e6a0: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
e6b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
e6c0: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
e6d0: 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
e6e0: 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
e6f0: 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e API3REF: Last In
e700: 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 sert Rowid {H122
e710: 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 20} <S10700>.**.
e720: 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e ** Each entry in
e730: 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 an SQLite table
e740: 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 has a unique 64
e750: 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 -bit signed.** i
e760: 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 nteger key calle
e770: 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 d the [ROWID | "
e780: 72 6f 77 69 64 22 5d 2e 20 54 68 65 20 72 6f 77 rowid"]. The row
e790: 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 id is always ava
e7a0: 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 ilable.** as an
e7b0: 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d undeclared colum
e7c0: 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f n named ROWID, O
e7d0: 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 ID, or _ROWID_ a
e7e0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a s long as those.
e7f0: 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 ** names are not
e800: 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 also used by ex
e810: 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
e820: 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a d columns. If.**
e830: 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 the table has a
e840: 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 column of type
e850: 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
e860: 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 KEY] then that
e870: 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f column.** is ano
e880: 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 ther alias for t
e890: 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 he rowid..**.**
e8a0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
e8b0: 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d urns the [rowid]
e8c0: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 of the most rec
e8d0: 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 ent.** successfu
e8e0: 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 l [INSERT] into
e8f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f the database fro
e900: 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 m the [database
e910: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 connection].** i
e920: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
e930: 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 ment. If no suc
e940: 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
e950: 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
e960: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 ccurred on that
e970: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
e980: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 ion, zero is ret
e990: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 urned..**.** If
e9a0: 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 an [INSERT] occu
e9b0: 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 rs within a trig
e9c0: 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 ger, then the [r
e9d0: 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 owid] of the ins
e9e0: 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 erted.** row is
e9f0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
ea00: 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 routine as long
ea10: 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 as the trigger
ea20: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 is running..** B
ea30: 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 ut once the trig
ea40: 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 ger terminates,
ea50: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
ea60: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 ed by this routi
ea70: 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f ne.** reverts to
ea80: 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 the last value
ea90: 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 inserted before
eaa0: 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65 the trigger fire
eab0: 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 d..**.** An [INS
eac0: 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 ERT] that fails
ead0: 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 due to a constra
eae0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 int violation is
eaf0: 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 not a.** succes
eb00: 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e sful [INSERT] an
eb10: 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 d does not chang
eb20: 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 e the value retu
eb30: 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 rned by this.**
eb40: 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 routine. Thus I
eb50: 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 NSERT OR FAIL, I
eb60: 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c NSERT OR IGNORE,
eb70: 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 INSERT OR ROLLB
eb80: 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 ACK,.** and INSE
eb90: 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 RT OR ABORT make
eba0: 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 no changes to t
ebb0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
ebc0: 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 of this.** routi
ebd0: 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e ne when their in
ebe0: 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 sertion fails.
ebf0: 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 When INSERT OR R
ec00: 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e EPLACE.** encoun
ec10: 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e ters a constrain
ec20: 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 t violation, it
ec30: 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 does not fail.
ec40: 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f The.** INSERT co
ec50: 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c ntinues to compl
ec60: 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 etion after dele
ec70: 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 ting rows that c
ec80: 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e aused.** the con
ec90: 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 straint problem
eca0: 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 so INSERT OR REP
ecb0: 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 LACE will always
ecc0: 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 change.** the r
ecd0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
ece0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a his interface..*
ecf0: 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 *.** For the pur
ed00: 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f poses of this ro
ed10: 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 utine, an [INSER
ed20: 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 T] is considered
ed30: 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 to.** be succes
ed40: 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 sful even if it
ed50: 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 is subsequently
ed60: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a rolled back..**.
ed70: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
ed80: 0a 2a 2a 20 5b 48 31 32 32 32 31 5d 20 5b 48 31 .** [H12221] [H1
ed90: 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 2223].**.** If a
eda0: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
edb0: 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 performs a new
edc0: 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 [INSERT] on the
edd0: 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 same.** database
ede0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
edf0: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c e the [sqlite3_l
ee00: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
ee10: 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ()].** function
ee20: 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 is running and t
ee30: 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 hus changes the
ee40: 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 last insert [row
ee50: 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 id],.** then the
ee60: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
ee70: 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 by [sqlite3_last
ee80: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
ee90: 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 is.** unpredict
eea0: 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e able and might n
eeb0: 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 ot equal either
eec0: 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e the old or the n
eed0: 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 ew.** last inser
eee0: 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 t [rowid]..*/.SQ
eef0: 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
ef00: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c _int64 sqlite3_l
ef10: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
ef20: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
ef30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 ** CAPI3REF: Cou
ef40: 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 nt The Number Of
ef50: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b Rows Modified {
ef60: 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30 30 3e H12240} <S10600>
ef70: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
ef80: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
ef90: 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 number of datab
efa0: 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 ase rows that we
efb0: 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 re changed.** or
efc0: 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c inserted or del
efd0: 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 eted by the most
efe0: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 recently comple
eff0: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
f000: 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 t.** on the [dat
f010: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
f020: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 ] specified by t
f030: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
f040: 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e er..** Only chan
f050: 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 ges that are dir
f060: 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 ectly specified
f070: 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c by the [INSERT],
f080: 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 [UPDATE],.** or
f090: 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
f0a0: 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e ent are counted.
f0b0: 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e Auxiliary chan
f0c0: 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a ges caused by.**
f0d0: 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f triggers or [fo
f0e0: 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e reign key action
f0f0: 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 s] are not count
f100: 65 64 2e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b ed. Use the.** [
f110: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
f120: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f anges()] functio
f130: 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f n to find the to
f140: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 tal number of ch
f150: 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 anges.** includi
f160: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ng changes cause
f170: 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e d by triggers an
f180: 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 d foreign key ac
f190: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 tions..**.** Cha
f1a0: 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 nges to a view t
f1b0: 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 hat are simulate
f1c0: 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 d by an [INSTEAD
f1d0: 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 OF trigger].**
f1e0: 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e are not counted.
f1f0: 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c Only real tabl
f200: 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f e changes are co
f210: 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 unted..**.** A "
f220: 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 row change" is a
f230: 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e change to a sin
f240: 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e gle row of a sin
f250: 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 gle table.** cau
f260: 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 sed by an INSERT
f270: 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 , DELETE, or UPD
f280: 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 ATE statement.
f290: 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 Rows that.** are
f2a0: 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 changed as side
f2b0: 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 effects of [REP
f2c0: 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 LACE] constraint
f2d0: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 resolution,.**
f2e0: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 rollback, ABORT
f2f0: 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f processing, [DRO
f300: 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 P TABLE], or by
f310: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 any other.** mec
f320: 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 hanisms do not c
f330: 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 ount as direct r
f340: 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a ow changes..**.*
f350: 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e * A "trigger con
f360: 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 text" is a scope
f370: 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 of execution th
f380: 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a at begins and.**
f390: 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 ends with the s
f3a0: 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 cript of a [CREA
f3b0: 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
f3c0: 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 gger]. .** Most
f3d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
f3e0: 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 re.** evaluated
f3f0: 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 outside of any t
f400: 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 rigger. This is
f410: 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 the "top level"
f420: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 .** trigger cont
f430: 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 ext. If a trigg
f440: 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 er fires from th
f450: 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a e top level, a.*
f460: 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f * new trigger co
f470: 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 ntext is entered
f480: 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f for the duratio
f490: 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a n of that one.**
f4a0: 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 trigger. Subtr
f4b0: 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 iggers create su
f4c0: 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 bcontexts for th
f4d0: 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a eir duration..**
f4e0: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c .** Calling [sql
f4f0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 ite3_exec()] or
f500: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
f510: 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 recursively doe
f520: 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 s.** not create
f530: 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f a new trigger co
f540: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ntext..**.** Thi
f550: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
f560: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
f570: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e direct row chan
f580: 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f ges in the.** mo
f590: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 st recent INSERT
f5a0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
f5b0: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 ETE statement wi
f5c0: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a thin the same.**
f5d0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
f5e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 ..**.** Thus, wh
f5f0: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 en called from t
f600: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 he top level, th
f610: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
f620: 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 rns the.** numbe
f630: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 r of changes in
f640: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
f650: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
f660: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
f670: 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 t also occurred
f680: 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c at the top level
f690: 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f . Within the bo
f6a0: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c dy of a trigger,
f6b0: 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f .** the sqlite3_
f6c0: 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 changes() interf
f6d0: 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 ace can be calle
f6e0: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 d to find the nu
f6f0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 mber of.** chang
f700: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 es in the most r
f710: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 ecently complete
f720: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 d INSERT, UPDATE
f730: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 , or DELETE.** s
f740: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
f750: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 the body of the
f760: 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a same trigger..**
f770: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 However, the nu
f780: 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f mber returned do
f790: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 es not include c
f7a0: 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 hanges.** caused
f7b0: 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 by subtriggers
f7c0: 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 since those have
f7d0: 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 their own conte
f7e0: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c xt..**.** See al
f7f0: 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
f800: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
f810: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 74 interface and t
f820: 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 he.** [count_cha
f830: 6e 67 65 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a nges pragma]..**
f840: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
f850: 3a 0a 2a 2a 20 5b 48 31 32 32 34 31 5d 20 5b 48 :.** [H12241] [H
f860: 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 12243].**.** If
f870: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
f880: 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
f890: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
f8a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
f8b0: 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ** while [sqlite
f8c0: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 3_changes()] is
f8d0: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
f8e0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a value returned.
f8f0: 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ** is unpredicta
f900: 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
f910: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 ingful..*/.SQLIT
f920: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
f930: 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 3_changes(sqlite
f940: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
f950: 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 3REF: Total Numb
f960: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 er Of Rows Modif
f970: 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 ied {H12260} <S1
f980: 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0600>.**.** This
f990: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
f9a0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
f9b0: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 row changes caus
f9c0: 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a ed by [INSERT],.
f9d0: 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b ** [UPDATE] or [
f9e0: 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e DELETE] statemen
f9f0: 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 ts since the [da
fa00: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
fa10: 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a n] was opened..*
fa20: 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c * The count incl
fa30: 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 udes all changes
fa40: 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 from all [CREAT
fa50: 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
fa60: 67 65 72 5d 20 0a 2a 2a 20 63 6f 6e 74 65 78 74 ger] .** context
fa70: 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 s and changes ma
fa80: 64 65 20 62 79 20 5b 66 6f 72 65 69 67 6e 20 6b de by [foreign k
fa90: 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 ey actions]. How
faa0: 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 ever,.** the cou
fab0: 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c nt does not incl
fac0: 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 ude changes used
fad0: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 to implement [R
fae0: 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 EPLACE] constrai
faf0: 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 nts,.** do rollb
fb00: 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 acks or ABORT pr
fb10: 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 ocessing, or [DR
fb20: 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 OP TABLE] proces
fb30: 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f sing. The.** co
fb40: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 unt does not inc
fb50: 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 lude rows of vie
fb60: 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 ws that fire an
fb70: 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 [INSTEAD OF trig
fb80: 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 ger],.** though
fb90: 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f if the INSTEAD O
fba0: 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 F trigger makes
fbb0: 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f changes of its o
fbc0: 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 wn, those change
fbd0: 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 s .** are counte
fbe0: 64 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 d..** The change
fbf0: 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 s are counted as
fc00: 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 soon as the sta
fc10: 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 tement that make
fc20: 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d s them is.** com
fc30: 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 pleted (when the
fc40: 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c statement handl
fc50: 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b e is passed to [
fc60: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
fc70: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
fc80: 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a finalize()])..**
fc90: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 .** See also the
fca0: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 [sqlite3_change
fcb0: 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 s()] interface a
fcc0: 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 nd the.** [count
fcd0: 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
fce0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
fcf0: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36 31 ents:.** [H12261
fd00: 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a 2a ] [H12263].**.**
fd10: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
fd20: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
fd30: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
fd40: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
fd50: 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
fd60: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
fd70: 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
fd80: 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
fd90: 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 .** returned is
fda0: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
fdb0: 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
fdc0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
fdd0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 int sqlite3_tota
fde0: 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 l_changes(sqlite
fdf0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
fe00: 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 3REF: Interrupt
fe10: 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 A Long-Running Q
fe20: 75 65 72 79 20 7b 48 31 32 32 37 30 7d 20 3c 53 uery {H12270} <S
fe30: 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 30500>.**.** Thi
fe40: 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 s function cause
fe50: 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 s any pending da
fe60: 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
fe70: 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a to abort and.**
fe80: 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 return at its e
fe90: 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e arliest opportun
fea0: 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e ity. This routin
feb0: 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a e is typically.*
fec0: 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 * called in resp
fed0: 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 onse to a user a
fee0: 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 ction such as pr
fef0: 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a essing "Cancel".
ff00: 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 ** or Ctrl-C whe
ff10: 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 re the user want
ff20: 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f s a long query o
ff30: 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 peration to halt
ff40: 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e .** immediately.
ff50: 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 .**.** It is saf
ff60: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
ff70: 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 outine from a th
ff80: 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 read different f
ff90: 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 rom the.** threa
ffa0: 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e d that is curren
ffb0: 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 tly running the
ffc0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 database operati
ffd0: 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 on. But it.** i
ffe0: 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 s not safe to ca
fff0: 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ll this routine
10000 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 with a [database
10010 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 connection] tha
10020 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f t.** is closed o
10030 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 r might close be
10040 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 fore sqlite3_int
10050 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 errupt() returns
10060 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 ..**.** If an SQ
10070 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 L operation is v
10080 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 ery nearly finis
10090 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 hed at the time
100a0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f when.** sqlite3_
100b0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 interrupt() is c
100c0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d alled, then it m
100d0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e ight not have an
100e0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 opportunity.**
100f0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 to be interrupte
10100 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 d and might cont
10110 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 inue to completi
10120 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c on..**.** An SQL
10130 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 operation that
10140 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 is interrupted w
10150 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
10160 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a TE_INTERRUPT]..*
10170 2a 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 * If the interru
10180 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 pted SQL operati
10190 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c on is an INSERT,
101a0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
101b0 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e TE.** that is in
101c0 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 side an explicit
101d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 transaction, th
101e0 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 en the entire tr
101f0 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c ansaction.** wil
10200 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b l be rolled back
10210 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a automatically..
10220 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
10230 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 3_interrupt(D) c
10240 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 all is in effect
10250 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 until all curre
10260 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 ntly running.**
10270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f SQL statements o
10280 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
10290 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 ection] D comple
102a0 74 65 2e 20 20 41 6e 79 20 6e 65 77 20 53 51 4c te. Any new SQL
102b0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 statements.** t
102c0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 hat are started
102d0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 after the sqlite
102e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
102f0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 ll and before th
10300 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 e .** running st
10310 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 atements reaches
10320 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 zero are interr
10330 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 upted as if they
10340 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e had been.** run
10350 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 ning prior to th
10360 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
10370 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 4e 65 77 upt() call. New
10380 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
10390 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
103a0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 ted after the ru
103b0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 nning statement
103c0 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 count reaches ze
103d0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 ro are.** not ef
103e0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 fected by the sq
103f0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
10400 29 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 )..** A call to
10410 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
10420 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 t(D) that occurs
10430 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 when there are
10440 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 no running.** SQ
10450 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 L statements is
10460 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 a no-op and has
10470 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c no effect on SQL
10480 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 statements.** t
10490 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 hat are started
104a0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 after the sqlite
104b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
104c0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a ll returns..**.*
104d0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
104e0 2a 2a 20 5b 48 31 32 32 37 31 5d 20 5b 48 31 32 ** [H12271] [H12
104f0 32 37 32 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 272].**.** If th
10500 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
10510 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 ction closes whi
10520 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 le [sqlite3_inte
10530 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 rrupt()].** is r
10540 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 unning then bad
10550 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 things will like
10560 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 ly happen..*/.SQ
10570 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
10580 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
10590 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
105a0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 * CAPI3REF: Dete
105b0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 rmine If An SQL
105c0 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d Statement Is Com
105d0 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20 3c plete {H10510} <
105e0 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S70200>.**.** Th
105f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
10600 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 useful during c
10610 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 ommand-line inpu
10620 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 t to determine i
10630 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 f the.** current
10640 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 ly entered text
10650 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 seems to form a
10660 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
10670 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 tement or.** if
10680 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 additional input
10690 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 is needed befor
106a0 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 e sending the te
106b0 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 xt into.** SQLit
106c0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 e for parsing.
106d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
106e0 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 eturn 1 if the i
106f0 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 nput string.** a
10700 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 ppears to be a c
10710 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
10720 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d ement. A statem
10730 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f ent is judged to
10740 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 be.** complete
10750 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 if it ends with
10760 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 a semicolon toke
10770 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 n and is not a p
10780 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 refix of a.** we
10790 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 ll-formed CREATE
107a0 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 TRIGGER stateme
107b0 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 nt. Semicolons
107c0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 that are embedde
107d0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 d within.** stri
107e0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 ng literals or q
107f0 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 uoted identifier
10800 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e names or commen
10810 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e ts are not.** in
10820 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 dependent tokens
10830 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 (they are part
10840 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 of the token in
10850 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a which they are.*
10860 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 * embedded) and
10870 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e thus do not coun
10880 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 t as a statement
10890 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 57 68 terminator. Wh
108a0 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 itespace.** and
108b0 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f comments that fo
108c0 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 llow the final s
108d0 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e emicolon are ign
108e0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ored..**.** Thes
108f0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
10900 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 n 0 if the state
10910 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 ment is incomple
10920 74 65 2e 20 20 49 66 20 61 0a 2a 2a 20 6d 65 6d te. If a.** mem
10930 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
10940 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 ails, then SQLIT
10950 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 E_NOMEM is retur
10960 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ned..**.** These
10970 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 routines do not
10980 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 parse the SQL s
10990 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a tatements thus.*
109a0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 * will not detec
109b0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 t syntactically
109c0 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a incorrect SQL..*
109d0 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 68 *.** If SQLite h
109e0 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 as not been init
109f0 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 ialized using [s
10a00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
10a10 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 e()] prior .** t
10a20 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 o invoking sqlit
10a30 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 e3_complete16()
10a40 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 then sqlite3_ini
10a50 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
10a60 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 oked.** automati
10a70 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 cally by sqlite3
10a80 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 _complete16().
10a90 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 If that initiali
10aa0 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a zation fails,.**
10ab0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e then the return
10ac0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
10ad0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
10ae0 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 will be non-zer
10af0 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 o.** regardless
10b00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
10b10 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 t the input SQL
10b20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 0a 2a 2a 0a is complete..**.
10b30 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
10b40 20 5b 48 31 30 35 31 31 5d 20 5b 48 31 30 35 31 [H10511] [H1051
10b50 32 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 2].**.** The inp
10b60 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ut to [sqlite3_c
10b70 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 omplete()] must
10b80 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e be a zero-termin
10b90 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 ated.** UTF-8 st
10ba0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ring..**.** The
10bb0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
10bc0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 3_complete16()]
10bd0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 must be a zero-t
10be0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
10bf0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 -16 string in na
10c00 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
10c10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
10c20 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c nt sqlite3_compl
10c30 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a ete(const char *
10c40 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 sql);.SQLITE_API
10c50 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d int sqlite3_com
10c60 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f plete16(const vo
10c70 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a id *sql);../*.**
10c80 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 CAPI3REF: Regis
10c90 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 ter A Callback T
10ca0 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f o Handle SQLITE_
10cb0 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 BUSY Errors {H12
10cc0 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 310} <S40400>.**
10cd0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
10ce0 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b sets a callback
10cf0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d function that m
10d00 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 ight be invoked
10d10 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 whenever.** an a
10d20 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 ttempt is made t
10d30 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 o open a databas
10d40 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f e table that ano
10d50 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f ther thread.** o
10d60 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f r process has lo
10d70 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 cked..**.** If t
10d80 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
10d90 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b is NULL, then [
10da0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 SQLITE_BUSY] or
10db0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
10dc0 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 OCKED].** is ret
10dd0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
10de0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 y upon encounter
10df0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 ing the lock. If
10e00 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 the busy callba
10e10 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c ck.** is not NUL
10e20 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c L, then the call
10e30 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 back will be inv
10e40 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 oked with two ar
10e50 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 guments..**.** T
10e60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
10e70 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 t to the handler
10e80 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
10e90 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 e void* pointer
10ea0 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 which.** is the
10eb0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
10ec0 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 o sqlite3_busy_h
10ed0 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 andler(). The s
10ee0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
10ef0 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 o.** the handler
10f00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 callback is the
10f10 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 number of times
10f20 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 that the busy h
10f30 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 andler has.** be
10f40 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 en invoked for t
10f50 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e his locking even
10f60 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 t. If the.** bu
10f70 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 sy callback retu
10f80 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 rns 0, then no a
10f90 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 dditional attemp
10fa0 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a ts are made to.*
10fb0 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 * access the dat
10fc0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 abase and [SQLIT
10fd0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 E_BUSY] or [SQLI
10fe0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
10ff0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
11000 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 * If the callbac
11010 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 k returns non-ze
11020 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 ro, then another
11030 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d attempt.** is m
11040 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 ade to open the
11050 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 database for rea
11060 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 ding and the cyc
11070 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a le repeats..**.*
11080 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f * The presence o
11090 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 f a busy handler
110a0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e does not guaran
110b0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c tee that it will
110c0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 be invoked.** w
110d0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 hen there is loc
110e0 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 k contention. If
110f0 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e SQLite determin
11100 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 es that invoking
11110 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e the busy.** han
11120 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c dler could resul
11130 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c t in a deadlock,
11140 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 it will go ahea
11150 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 d and return [SQ
11160 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 LITE_BUSY].** or
11170 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
11180 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 LOCKED] instead
11190 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 of invoking the
111a0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
111b0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e Consider a scen
111c0 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 ario where one p
111d0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
111e0 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 g a read lock th
111f0 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 at.** it is tryi
11200 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ng to promote to
11210 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b a reserved lock
11220 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 and.** a second
11230 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
11240 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c ing a reserved l
11250 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 ock that it is t
11260 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d rying.** to prom
11270 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 ote to an exclus
11280 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 ive lock. The f
11290 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e irst process can
112a0 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 not proceed.** b
112b0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f ecause it is blo
112c0 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f cked by the seco
112d0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e nd and the secon
112e0 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 d process cannot
112f0 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 .** proceed beca
11300 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 use it is blocke
11310 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 d by the first.
11320 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 If both process
11330 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 es.** invoke the
11340 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 busy handlers,
11350 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b neither will mak
11360 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 e any progress.
11370 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 Therefore,.** S
11380 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 QLite returns [S
11390 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 QLITE_BUSY] for
113a0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 the first proces
113b0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 s, hoping that t
113c0 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 his.** will indu
113d0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f ce the first pro
113e0 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 cess to release
113f0 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e its read lock an
11400 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 d allow.** the s
11410 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f econd process to
11420 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 proceed..**.**
11430 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 The default busy
11440 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c callback is NUL
11450 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 L..**.** The [SQ
11460 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 LITE_BUSY] error
11470 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f is converted to
11480 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
11490 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 LOCKED].** when
114a0 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 SQLite is in the
114b0 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 middle of a lar
114c0 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 ge transaction w
114d0 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 here all the.**
114e0 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 changes will not
114f0 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e fit into the in
11500 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 -memory cache.
11510 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 SQLite will.** a
11520 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 lready hold a RE
11530 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 SERVED lock on t
11540 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
11550 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a , but it needs.*
11560 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 * to promote thi
11570 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 s lock to EXCLUS
11580 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 IVE so that it c
11590 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a an spill cache.*
115a0 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 * pages into the
115b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
115c0 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 ithout harm to c
115d0 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 oncurrent.** rea
115e0 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 ders. If it is
115f0 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 unable to promot
11600 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e e the lock, then
11610 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a the in-memory.*
11620 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 * cache will be
11630 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e left in an incon
11640 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e sistent state an
11650 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a d so the error.*
11660 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 * code is promot
11670 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 ed from the rela
11680 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 tively benign [S
11690 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a QLITE_BUSY] to.*
116a0 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 * the more sever
116b0 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f e [SQLITE_IOERR_
116c0 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 BLOCKED]. This
116d0 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f error code promo
116e0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 tion.** forces a
116f0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c n automatic roll
11700 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e back of the chan
11710 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a ges. See the.**
11720 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 <a href="/cvstr
11730 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 ac/wiki?p=Corrup
11740 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 tionFollowingBus
11750 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 yError">.** Corr
11760 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 uptionFollowingB
11770 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b usyError</a> wik
11780 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 i page for a dis
11790 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a cussion of why.*
117a0 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 * this is import
117b0 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 ant..**.** There
117c0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 can only be a s
117d0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c ingle busy handl
117e0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 er defined for e
117f0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 ach.** [database
11800 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 connection]. S
11810 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 etting a new bus
11820 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 y handler clears
11830 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 any.** previous
11840 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 ly set handler.
11850 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 Note that calli
11860 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ng [sqlite3_busy
11870 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 _timeout()].** w
11880 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 ill also set or
11890 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 clear the busy h
118a0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 andler..**.** Th
118b0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 e busy callback
118c0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 should not take
118d0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 any actions whic
118e0 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 h modify the.**
118f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11900 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
11910 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
11920 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 r. Any such act
11930 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 ions.** result i
11940 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
11950 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 52 65 71 vior..** .** Req
11960 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
11970 31 32 33 31 31 5d 20 5b 48 31 32 33 31 32 5d 20 12311] [H12312]
11980 5b 48 31 32 33 31 34 5d 20 5b 48 31 32 33 31 36 [H12314] [H12316
11990 5d 20 5b 48 31 32 33 31 38 5d 0a 2a 2a 0a 2a 2a ] [H12318].**.**
119a0 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 A busy handler
119b0 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 must not close t
119c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
119d0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 ection.** or [pr
119e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
119f0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 ] that invoked t
11a00 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
11a10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
11a20 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
11a30 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
11a40 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 , int(*)(void*,i
11a50 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a nt), void*);../*
11a60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
11a70 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 t A Busy Timeout
11a80 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31 {H12340} <S4041
11a90 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 0>.**.** This ro
11aa0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 utine sets a [sq
11ab0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
11ac0 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 er | busy handle
11ad0 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a r] that sleeps.*
11ae0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 * for a specifie
11af0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 d amount of time
11b00 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 when a table is
11b10 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 locked. The ha
11b20 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c ndler.** will sl
11b30 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d eep multiple tim
11b40 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 es until at leas
11b50 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
11b60 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a nds of sleeping.
11b70 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 ** have accumula
11b80 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 ted. {H12343} Af
11b90 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 ter "ms" millise
11ba0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e conds of sleepin
11bb0 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 g,.** the handle
11bc0 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 r returns 0 whic
11bd0 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 h causes [sqlite
11be0 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 3_step()] to ret
11bf0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 urn.** [SQLITE_B
11c00 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
11c10 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a IOERR_BLOCKED]..
11c20 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 **.** Calling th
11c30 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 is routine with
11c40 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 an argument less
11c50 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 than or equal t
11c60 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 o zero.** turns
11c70 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e off all busy han
11c80 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 dlers..**.** The
11c90 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
11ca0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
11cb0 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 dler for a parti
11cc0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
11cd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
11ce0 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d ny any given mom
11cf0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 ent. If another
11d00 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a busy handler.**
11d10 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 was defined (u
11d20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 sing [sqlite3_bu
11d30 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 sy_handler()]) p
11d40 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a rior to calling.
11d50 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c ** this routine,
11d60 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 that other busy
11d70 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 handler is clea
11d80 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 red..**.** Requi
11d90 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
11da0 33 34 31 5d 20 5b 48 31 32 33 34 33 5d 20 5b 48 341] [H12343] [H
11db0 31 32 33 34 34 5d 0a 2a 2f 0a 53 51 4c 49 54 45 12344].*/.SQLITE
11dc0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
11dd0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 _busy_timeout(sq
11de0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b lite3*, int ms);
11df0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
11e00 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f : Convenience Ro
11e10 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 utines For Runni
11e20 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 33 ng Queries {H123
11e30 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 70} <S10000>.**.
11e40 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 ** Definition: A
11e50 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 <b>result table
11e60 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 </b> is memory d
11e70 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 ata structure cr
11e80 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 eated by the.**
11e90 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
11ea0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e le()] interface.
11eb0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 A result table
11ec0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 records the.**
11ed0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 complete query r
11ee0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 esults from one
11ef0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e or more queries.
11f00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
11f10 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 conceptually ha
11f20 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f s a number of ro
11f30 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 ws and columns.
11f40 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 But.** these nu
11f50 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 mbers are not pa
11f60 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 rt of the result
11f70 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 table itself.
11f80 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 These.** numbers
11f90 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 are obtained se
11fa0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e parately. Let N
11fb0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
11fc0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 f rows.** and M
11fd0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
11fe0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 columns..**.**
11ff0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 A result table i
12000 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
12010 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 inters to zero-t
12020 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
12030 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 strings..** Ther
12040 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c e are (N+1)*M el
12050 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 ements in the ar
12060 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 ray. The first
12070 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 M pointers point
12080 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d .** to zero-term
12090 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
120a0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 hat contain the
120b0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f names of the co
120c0 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 lumns..** The re
120d0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 maining entries
120e0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 all point to que
120f0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c ry results. NUL
12100 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a L values result.
12110 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** in NULL point
12120 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ers. All other
12130 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 values are in th
12140 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 eir UTF-8 zero-t
12150 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
12160 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
12170 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 on as returned b
12180 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
12190 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_text()]..**.**
121a0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
121b0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 might consist of
121c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d one or more mem
121d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
121e0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
121f0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 fe to pass a res
12200 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 ult table direct
12210 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ly to [sqlite3_f
12220 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 ree()]..** A res
12230 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 ult table should
12240 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
12250 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
12260 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a ree_table()]..**
12270 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c .** As an exampl
12280 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 e of the result
12290 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 table format, su
122a0 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 ppose a query re
122b0 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f sult.** is as fo
122c0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
122d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
122e0 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 * Name
122f0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 | Age.**
12300 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d -----------
12310 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 ------------.**
12320 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 Alice
12330 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 | 43.**
12340 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 Bob |
12350 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 28.** Cin
12360 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a dy | 21.**
12370 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
12380 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 ote>.**.** There
12390 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 are two column
123a0 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 (M==2) and three
123b0 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 rows (N==3). T
123c0 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c hus the.** resul
123d0 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e t table has 8 en
123e0 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 tries. Suppose
123f0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
12400 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e is stored.** in
12410 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 an array names
12420 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 azResult. Then
12430 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 azResult holds t
12440 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a his content:.**.
12450 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
12460 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 pre>.** a
12470 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d zResult[0] =
12480 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 "Name";.**
12490 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
124a0 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 1] = "Age";.**
124b0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
124c0 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 91;2] = "Alice";
124d0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
124e0 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 ult[3] = "43
124f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
12500 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 esult[4] = "
12510 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Bob";.**
12520 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 azResult[5]
12530 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 = "28";.**
12540 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 azResult[6
12550 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 ] = "Cindy";.**
12560 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
12570 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a #91;7] = "21";.*
12580 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
12590 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 uote>.**.** The
125a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
125b0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 e() function eva
125c0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f luates one or mo
125d0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d re.** semicolon-
125e0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 separated SQL st
125f0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 atements in the
12600 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
12610 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 UTF-8.** string
12620 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d of its 2nd param
12630 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e eter. It return
12640 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
12650 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 to the.** point
12660 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 er given in its
12670 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 3rd parameter..*
12680 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 *.** After the c
12690 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
126a0 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 has finished usi
126b0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 ng the result, i
126c0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 t should.** pass
126d0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 the pointer to
126e0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
126f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
12700 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 _table() in orde
12710 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 r to.** release
12720 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 the memory that
12730 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 was malloced. B
12740 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 ecause of the wa
12750 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 y the.** [sqlite
12760 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 3_malloc()] happ
12770 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 ens within sqlit
12780 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 e3_get_table(),
12790 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 the calling.** f
127a0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 unction must not
127b0 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 try to call [sq
127c0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 lite3_free()] di
127d0 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a rectly. Only.**
127e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 [sqlite3_free_t
127f0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 able()] is able
12800 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d to release the m
12810 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 emory properly a
12820 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a nd safely..**.**
12830 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
12840 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 _table() interfa
12850 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 ce is implemente
12860 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 d as a wrapper a
12870 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 round.** [sqlite
12880 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 3_exec()]. The
12890 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
128a0 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 e() routine does
128b0 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 not have access
128c0 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 .** to any inter
128d0 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 nal data structu
128e0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 res of SQLite.
128f0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 It uses only the
12900 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 public.** inter
12910 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 face defined her
12920 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 e. As a consequ
12930 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 ence, errors tha
12940 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a t occur in the.*
12950 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 * wrapper layer
12960 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 outside of the i
12970 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 nternal [sqlite3
12980 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 _exec()] call ar
12990 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 e not.** reflect
129a0 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 ed in subsequent
129b0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
129c0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 e3_errcode()] or
129d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
129e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ()]..**.** Requi
129f0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
12a00 33 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48 371] [H12373] [H
12a10 31 32 33 37 34 5d 20 5b 48 31 32 33 37 36 5d 20 12374] [H12376]
12a20 5b 48 31 32 33 37 39 5d 20 5b 48 31 32 33 38 32 [H12379] [H12382
12a30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
12a40 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f int sqlite3_get_
12a50 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 table(. sqlite3
12a60 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f *db, /
12a70 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 * An open databa
12a80 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 se */. const ch
12a90 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a ar *zSql, /*
12aa0 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
12ab0 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a ated */. char *
12ac0 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 **pazResult,
12ad0 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 /* Results of th
12ae0 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 e query */. int
12af0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 *pnRow,
12b00 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
12b10 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 result rows writ
12b20 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e ten here */. in
12b30 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 t *pnColumn,
12b40 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
12b50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 result columns
12b60 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
12b70 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 char **pzErrms
12b80 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 g /* Error
12b90 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
12ba0 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 e */.);.SQLITE_A
12bb0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
12bc0 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 free_table(char
12bd0 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a **result);../*.*
12be0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d * CAPI3REF: Form
12bf0 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 atted String Pri
12c00 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 nting Functions
12c10 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30 30 30 {H17400} <S70000
12c20 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 ><S20000>.**.**
12c30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
12c40 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f re work-alikes o
12c50 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 f the "printf()"
12c60 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 family of funct
12c70 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 ions.** from the
12c80 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
12c90 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ary..**.** The s
12ca0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
12cb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 and sqlite3_vmp
12cc0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 rintf() routines
12cd0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 write their.**
12ce0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d results into mem
12cf0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
12d00 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
12d10 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 c()]..** The str
12d20 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 ings returned by
12d30 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 these two routi
12d40 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a nes should be.**
12d50 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 released by [sq
12d60 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 lite3_free()].
12d70 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 Both routines re
12d80 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 turn a.** NULL p
12d90 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 ointer if [sqlit
12da0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 e3_malloc()] is
12db0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
12dc0 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d te enough.** mem
12dd0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
12de0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
12df0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 ..**.** In sqlit
12e00 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f e3_snprintf() ro
12e10 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 utine is similar
12e20 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 to "snprintf()"
12e30 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 from.** the sta
12e40 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
12e50 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 The result is
12e60 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
12e70 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c .** buffer suppl
12e80 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e ied as the secon
12e90 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 d parameter whos
12ea0 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 e size is given
12eb0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 by.** the first
12ec0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 parameter. Note
12ed0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f that the order o
12ee0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 f the.** first t
12ef0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 wo parameters is
12f00 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 reversed from s
12f10 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 nprintf(). This
12f20 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 is an.** histor
12f30 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 ical accident th
12f40 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 at cannot be fix
12f50 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ed without break
12f60 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ing.** backwards
12f70 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 compatibility.
12f80 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 Note also that
12f90 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
12fa0 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 ().** returns a
12fb0 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 pointer to its b
12fc0 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 uffer instead of
12fd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
12fe0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 * characters act
12ff0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e ually written in
13000 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 to the buffer.
13010 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a We admit that.**
13020 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
13030 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 haracters writte
13040 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 n would be a mor
13050 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a e useful return.
13060 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 ** value but we
13070 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 cannot change th
13080 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
13090 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 of sqlite3_snpr
130a0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 intf().** now wi
130b0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 thout breaking c
130c0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
130d0 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 .** As long as t
130e0 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 he buffer size i
130f0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a s greater than z
13100 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 ero, sqlite3_snp
13110 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 rintf().** guara
13120 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 ntees that the b
13130 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 uffer is always
13140 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
13150 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 The first.** p
13160 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 arameter "n" is
13170 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f the total size o
13180 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e f the buffer, in
13190 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f cluding space fo
131a0 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 r.** the zero te
131b0 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 rminator. So th
131c0 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 e longest string
131d0 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d that can be com
131e0 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 pletely.** writt
131f0 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 en will be n-1 c
13200 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a haracters..**.**
13210 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
13220 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f all implement so
13230 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f me additional fo
13240 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 rmatting.** opti
13250 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 ons that are use
13260 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 ful for construc
13270 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 ting SQL stateme
13280 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 nts..** All of t
13290 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 he usual printf(
132a0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 ) formatting opt
132b0 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 ions apply. In
132c0 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a addition, there.
132d0 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 ** is are "%q",
132e0 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f "%Q", and "%z" o
132f0 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ptions..**.** Th
13300 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b e %q option work
13310 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 s like %s in tha
13320 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 t it substitutes
13330 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 a null-terminat
13340 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f ed.** string fro
13350 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c m the argument l
13360 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 ist. But %q als
13370 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 o doubles every
13380 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a '\'' character..
13390 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 ** %q is designe
133a0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 d for use inside
133b0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 a string litera
133c0 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 l. By doubling
133d0 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 each '\''.** cha
133e0 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 racter it escape
133f0 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 s that character
13400 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 and allows it t
13410 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e o be inserted in
13420 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 to.** the string
13430 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d ..**.** For exam
13440 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 ple, assume the
13450 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 string variable
13460 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 zText contains t
13470 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a ext as follows:.
13480 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
13490 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
134a0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 *zText = "It's
134b0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a a happy day!";.*
134c0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
134d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 uote>.**.** One
134e0 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 can use this tex
134f0 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 t in an SQL stat
13500 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 ement as follows
13510 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
13520 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
13530 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 ar *zSQL = sqlit
13540 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 e3_mprintf("INSE
13550 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 RT INTO table VA
13560 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 LUES('%q')", zTe
13570 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 xt);.** sqlite3
13580 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 _exec(db, zSQL,
13590 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 0, 0, 0);.** sq
135a0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 lite3_free(zSQL)
135b0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
135c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 ckquote>.**.** B
135d0 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f ecause the %q fo
135e0 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 rmat string is u
135f0 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 sed, the '\'' ch
13600 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 aracter in zText
13610 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 .** is escaped a
13620 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 nd the SQL gener
13630 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f ated is as follo
13640 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
13650 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
13660 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
13670 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 e1 VALUES('It''s
13680 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a a happy day!').
13690 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
136a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 quote>.**.** Thi
136b0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 s is correct. H
136c0 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e ad we used %s in
136d0 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 stead of %q, the
136e0 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a generated SQL.*
136f0 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f * would have loo
13700 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a ked like this:.*
13710 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
13720 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
13730 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
13740 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 LUES('It's a hap
13750 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f py day!');.** </
13760 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
13770 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 >.**.** This sec
13780 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 ond example is a
13790 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 n SQL syntax err
137a0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 or. As a genera
137b0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c l rule you shoul
137c0 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 d.** always use
137d0 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 %q instead of %s
137e0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 when inserting
137f0 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 text into a stri
13800 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a ng literal..**.*
13810 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 * The %Q option
13820 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 works like %q ex
13830 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 cept it also add
13840 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 s single quotes
13850 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 around.** the ou
13860 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 tside of the tot
13870 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 al string. Addi
13880 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 tionally, if the
13890 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 parameter in th
138a0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 e.** argument li
138b0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 st is a NULL poi
138c0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 nter, %Q substit
138d0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e utes the text "N
138e0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a ULL" (without.**
138f0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 single quotes)
13900 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 in place of the
13910 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 %Q option. So,
13920 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 for example, one
13930 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a could say:.**.*
13940 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
13950 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 re>.** char *zS
13960 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 QL = sqlite3_mpr
13970 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 intf("INSERT INT
13980 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 O table VALUES(%
13990 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 Q)", zText);.**
139a0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
139b0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
139c0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
139d0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
139e0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
139f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
13a00 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 above will rende
13a10 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 r a correct SQL
13a20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 statement in the
13a30 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c zSQL.** variabl
13a40 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 e even if the zT
13a50 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 ext variable is
13a60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
13a70 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 **.** The "%z" f
13a80 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
13a90 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c works exactly l
13aa0 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68 ike "%s" with th
13ab0 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 e.** addition th
13ac0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 at after the str
13ad0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 ing has been rea
13ae0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 d and copied int
13af0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c o.** the result,
13b00 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
13b10 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 ] is called on t
13b20 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e he input string.
13b30 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 52 65 71 {END}.**.** Req
13b40 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
13b50 31 37 34 30 33 5d 20 5b 48 31 37 34 30 36 5d 20 17403] [H17406]
13b60 5b 48 31 37 34 30 37 5d 0a 2a 2f 0a 53 51 4c 49 [H17407].*/.SQLI
13b70 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c TE_API char *sql
13b80 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e ite3_mprintf(con
13b90 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 st char*,...);.S
13ba0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a QLITE_API char *
13bb0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
13bc0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 (const char*, va
13bd0 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 _list);.SQLITE_A
13be0 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 PI char *sqlite3
13bf0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
13c00 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
13c10 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
13c20 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
13c30 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 llocation Subsys
13c40 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 tem {H17300} <S2
13c50 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0000>.**.** The
13c60 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 SQLite core use
13c70 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f s these three ro
13c80 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f utines for all o
13c90 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 f its own.** int
13ca0 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ernal memory all
13cb0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 ocation needs. "
13cc0 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 Core" in the pre
13cd0 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a vious sentence.*
13ce0 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 * does not inclu
13cf0 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 de operating-sys
13d00 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 tem specific VFS
13d10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
13d20 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 The.** Windows
13d30 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 VFS uses native
13d40 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
13d50 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 ee() for some op
13d60 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
13d70 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c The sqlite3_mall
13d80 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 oc() routine ret
13d90 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
13da0 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 o a block.** of
13db0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 memory at least
13dc0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 N bytes in lengt
13dd0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 h, where N is th
13de0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 e parameter..**
13df0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f If sqlite3_mallo
13e00 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f c() is unable to
13e10 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 obtain sufficie
13e20 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 nt free.** memor
13e30 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 y, it returns a
13e40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 NULL pointer. I
13e50 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
13e60 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f N to.** sqlite3_
13e70 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f malloc() is zero
13e80 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 or negative the
13e90 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 n sqlite3_malloc
13ea0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 () returns.** a
13eb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
13ec0 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 .** Calling sqli
13ed0 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 te3_free() with
13ee0 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f a pointer previo
13ef0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a usly returned.**
13f00 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c by sqlite3_mall
13f10 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
13f20 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 realloc() releas
13f30 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 es that memory s
13f40 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 o.** that it mig
13f50 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 ht be reused. T
13f60 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 he sqlite3_free(
13f70 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 ) routine is.**
13f80 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 a no-op if is ca
13f90 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
13fa0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 pointer. Passi
13fb0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ng a NULL pointe
13fc0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f r.** to sqlite3_
13fd0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 free() is harmle
13fe0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 ss. After being
13ff0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a freed, memory.*
14000 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 * should neither
14010 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 be read nor wri
14020 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 tten. Even read
14030 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ing previously f
14040 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d reed.** memory m
14050 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 ight result in a
14060 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
14070 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 ult or other sev
14080 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 ere error..** Me
14090 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c mory corruption,
140a0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
140b0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 fault, or other
140c0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 severe error.**
140d0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
140e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
140f0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
14100 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
14110 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 that.** was not
14120 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
14130 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
14140 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
14150 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 oc()..**.** The
14160 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
14170 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
14180 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 mpts to resize a
14190 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 .** prior memory
141a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 allocation to b
141b0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 e at least N byt
141c0 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 es, where N is t
141d0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 he.** second par
141e0 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d ameter. The mem
141f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 ory allocation t
14200 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 o be resized is
14210 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 the first.** par
14220 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 ameter. If the
14230 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
14240 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
14250 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c oc().** is a NUL
14260 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 L pointer then i
14270 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 ts behavior is i
14280 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c dentical to call
14290 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d ing.** sqlite3_m
142a0 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e alloc(N) where N
142b0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 is the second p
142c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
142d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a te3_realloc()..*
142e0 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 * If the second
142f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
14300 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 ite3_realloc() i
14310 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 s zero or.** neg
14320 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 ative then the b
14330 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 ehavior is exact
14340 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 ly the same as c
14350 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 alling.** sqlite
14360 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 3_free(P) where
14370 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 P is the first p
14380 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
14390 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a te3_realloc()..*
143a0 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f * sqlite3_reallo
143b0 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f c() returns a po
143c0 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 inter to a memor
143d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
143e0 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 of at least N by
143f0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e tes in size or N
14400 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e ULL if sufficien
14410 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 t memory is unav
14420 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d ailable..** If M
14430 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 is the size of
14440 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
14450 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e tion, then min(N
14460 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 ,M) bytes.** of
14470 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
14480 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 tion are copied
14490 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 into the beginni
144a0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 ng of buffer ret
144b0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 urned.** by sqli
144c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e te3_realloc() an
144d0 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f d the prior allo
144e0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e cation is freed.
144f0 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 .** If sqlite3_r
14500 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 ealloc() returns
14510 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 NULL, then the
14520 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
14530 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 .** is not freed
14540 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f ..**.** The memo
14550 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ry returned by s
14560 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
14570 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c and sqlite3_real
14580 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 loc().** is alwa
14590 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 ys aligned to at
145a0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 least an 8 byte
145b0 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d boundary. {END}
145c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 .**.** The defau
145d0 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f lt implementatio
145e0 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 n of the memory
145f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
14600 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 stem uses.** the
14610 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c malloc(), reall
14620 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
14630 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 provided by the
14640 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
14650 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 ry..** {H17382}
14660 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 However, if SQLi
14670 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
14680 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 ith the.** SQLIT
14690 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 E_MEMORY_SIZE=<i
146a0 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 >NNN</i> C prepr
146b0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 ocessor macro (w
146c0 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a here <i>NNN</i>.
146d0 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ** is an integer
146e0 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 ), then SQLite c
146f0 72 65 61 74 65 20 61 20 73 74 61 74 69 63 20 61 reate a static a
14700 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 rray of at least
14710 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 .** <i>NNN</i> b
14720 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 ytes in size and
14730 20 75 73 65 73 20 74 68 61 74 20 61 72 72 61 79 uses that array
14740 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
14750 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 dynamic.** memor
14760 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
14770 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 ds. {END} Addit
14780 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ional memory all
14790 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a ocator options.*
147a0 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 * may be added i
147b0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
147c0 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 s..**.** In SQLi
147d0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
147e0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 and 3.5.1, it w
147f0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 as possible to d
14800 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c efine.** the SQL
14810 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f ITE_OMIT_MEMORY_
14820 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 ALLOCATION which
14830 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 would cause the
14840 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 built-in.** imp
14850 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
14860 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f hese routines to
14870 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 be omitted. Th
14880 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a at capability.**
14890 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 is no longer pr
148a0 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 ovided. Only bu
148b0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
148c0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 locators can be
148d0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 used..**.** The
148e0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 Windows OS inter
148f0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 face layer calls
14900 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d .** the system m
14910 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
14920 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e () directly when
14930 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 converting.** f
14940 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e ilenames between
14950 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 the UTF-8 encod
14960 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 ing used by SQLi
14970 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 te.** and whatev
14980 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f er filename enco
14990 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 ding is used by
149a0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 the particular W
149b0 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c indows.** instal
149c0 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 lation. Memory
149d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
149e0 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 s are detected,
149f0 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 but.** they are
14a00 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 reported back as
14a10 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 [SQLITE_CANTOPE
14a20 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 N] or.** [SQLITE
14a30 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 _IOERR] rather t
14a40 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 han [SQLITE_NOME
14a50 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 M]..**.** Requir
14a60 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 ements:.** [H173
14a70 30 33 5d 20 5b 48 31 37 33 30 34 5d 20 5b 48 31 03] [H17304] [H1
14a80 37 33 30 35 5d 20 5b 48 31 37 33 30 36 5d 20 5b 7305] [H17306] [
14a90 48 31 37 33 31 30 5d 20 5b 48 31 37 33 31 32 5d H17310] [H17312]
14aa0 20 5b 48 31 37 33 31 35 5d 20 5b 48 31 37 33 31 [H17315] [H1731
14ab0 38 5d 0a 2a 2a 20 5b 48 31 37 33 32 31 5d 20 5b 8].** [H17321] [
14ac0 48 31 37 33 32 32 5d 20 5b 48 31 37 33 32 33 5d H17322] [H17323]
14ad0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 .**.** The point
14ae0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 er arguments to
14af0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
14b00 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
14b10 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 alloc()].** must
14b20 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 be either NULL
14b30 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 or else pointers
14b40 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
14b50 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 prior.** invoca
14b60 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
14b70 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 _malloc()] or [s
14b80 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
14b90 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e ] that have.** n
14ba0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 ot yet been rele
14bb0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ased..**.** The
14bc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
14bd0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 not read or wri
14be0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a te any part of.*
14bf0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d * a block of mem
14c00 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 ory after it has
14c10 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 been released u
14c20 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
14c30 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c _free()] or [sql
14c40 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e ite3_realloc()].
14c50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
14c60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c oid *sqlite3_mal
14c70 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 loc(int);.SQLITE
14c80 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
14c90 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a e3_realloc(void*
14ca0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 , int);.SQLITE_A
14cb0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
14cc0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a free(void*);../*
14cd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
14ce0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 mory Allocator S
14cf0 74 61 74 69 73 74 69 63 73 20 7b 48 31 37 33 37 tatistics {H1737
14d00 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 0} <S30210>.**.*
14d10 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 * SQLite provide
14d20 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 s these two inte
14d30 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 rfaces for repor
14d40 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 ting on the stat
14d50 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 us.** of the [sq
14d60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c lite3_malloc()],
14d70 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
14d80 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
14d90 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f realloc()].** ro
14da0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f utines, which fo
14db0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 rm the built-in
14dc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
14dd0 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a n subsystem..**.
14de0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
14df0 0a 2a 2a 20 5b 48 31 37 33 37 31 5d 20 5b 48 31 .** [H17371] [H1
14e00 37 33 37 33 5d 20 5b 48 31 37 33 37 34 5d 20 5b 7373] [H17374] [
14e10 48 31 37 33 37 35 5d 0a 2a 2f 0a 53 51 4c 49 54 H17375].*/.SQLIT
14e20 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
14e30 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
14e40 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 ry_used(void);.S
14e50 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
14e60 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
14e70 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
14e80 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b (int resetFlag);
14e90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
14ea0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 : Pseudo-Random
14eb0 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 Number Generator
14ec0 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30 {H17390} <S2000
14ed0 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 0>.**.** SQLite
14ee0 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d contains a high-
14ef0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 quality pseudo-r
14f00 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e andom number gen
14f10 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 erator (PRNG) us
14f20 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 ed to.** select
14f30 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 random [ROWID |
14f40 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 ROWIDs] when ins
14f50 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 erting new recor
14f60 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 ds into a table
14f70 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 that.** already
14f80 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 uses the largest
14f90 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 possible [ROWID
14fa0 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 ]. The PRNG is
14fb0 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a also used for.**
14fc0 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 the build-in ra
14fd0 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f ndom() and rando
14fe0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 mblob() SQL func
14ff0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 tions. This int
15000 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a erface allows.**
15010 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f applications to
15020 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 access the same
15030 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 PRNG for other
15040 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 purposes..**.**
15050 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 A call to this r
15060 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 outine stores N
15070 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e bytes of randomn
15080 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 ess into buffer
15090 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 P..**.** The fir
150a0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 st time this rou
150b0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 tine is invoked
150c0 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c (either internal
150d0 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 ly or by.** the
150e0 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 application) the
150f0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 PRNG is seeded
15100 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 using randomness
15110 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
15120 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 m the xRandomnes
15130 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
15140 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
15150 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
15160 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 On all subseque
15170 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 nt invocations,
15180 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f the pseudo-rando
15190 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 mness is generat
151a0 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 ed.** internally
151b0 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 and without rec
151c0 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 ourse to the [sq
151d0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 lite3_vfs] xRand
151e0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 omness.** method
151f0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
15200 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 32 ents:.** [H17392
15210 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
15220 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e void sqlite3_ran
15230 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 domness(int N, v
15240 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid *P);../*.**
15250 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
15260 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 e-Time Authoriza
15270 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b tion Callbacks {
15280 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e H12500} <S70100>
15290 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
152a0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ine registers a
152b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
152c0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 ack with a parti
152d0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
152e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 se connection],
152f0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 supplied in the
15300 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
15310 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ** The authorize
15320 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
15330 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 voked as SQL sta
15340 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e tements are bein
15350 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 g compiled.** by
15360 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
15370 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
15380 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 ants [sqlite3_pr
15390 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 epare_v2()],.**
153a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
153b0 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 16()] and [sqlit
153c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
153d0 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a )]. At various.
153e0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 ** points during
153f0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e the compilation
15400 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 process, as log
15410 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 ic is being crea
15420 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 ted.** to perfor
15430 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e m various action
15440 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 s, the authorize
15450 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
15460 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 voked to.** see
15470 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 if those actions
15480 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 are allowed. T
15490 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
154a0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a llback should.**
154b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
154c0 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 OK] to allow the
154d0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 action, [SQLITE
154e0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 _IGNORE] to disa
154f0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 llow the.** spec
15500 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 ific action but
15510 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 allow the SQL st
15520 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 atement to conti
15530 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d nue to be.** com
15540 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 piled, or [SQLIT
15550 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 E_DENY] to cause
15560 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 the entire SQL
15570 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a statement to be.
15580 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 ** rejected with
15590 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74 an error. If t
155a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
155b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a llback returns.*
155c0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 * any value othe
155d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 r than [SQLITE_I
155e0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f GNORE], [SQLITE_
155f0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OK], or [SQLITE_
15600 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 DENY].** then th
15610 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
15620 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
15630 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
15640 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 triggered.** th
15650 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c e authorizer wil
15660 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
15670 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
15680 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c .** When the cal
15690 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
156a0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 QLITE_OK], that
156b0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 means the operat
156c0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 ion.** requested
156d0 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 is ok. When th
156e0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
156f0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d ns [SQLITE_DENY]
15700 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 , the.** [sqlite
15710 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
15720 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 or equivalent ca
15730 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
15740 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 d the.** authori
15750 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 zer will fail wi
15760 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 th an error mess
15770 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 age explaining t
15780 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 hat.** access is
15790 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 denied. .**.**
157a0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
157b0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
157c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
157d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
157e0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 third.** paramet
157f0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
15800 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
15810 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68 () interface. Th
15820 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
15830 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c er.** to the cal
15840 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
15850 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 ger [SQLITE_COPY
15860 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 | action code]
15870 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a that specifies.*
15880 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 * the particular
15890 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
158a0 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 thorized. The th
158b0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 ird through sixt
158c0 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 h parameters.**
158d0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
158e0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 are zero-termina
158f0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 ted strings that
15900 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f contain additio
15910 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 nal.** details a
15920 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 bout the action
15930 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
15940 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 ..**.** If the a
15950 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
15960 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 QLITE_READ].** a
15970 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 nd the callback
15980 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
15990 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 IGNORE] then the
159a0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
159b0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 atement] stateme
159c0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 nt is constructe
159d0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a d to substitute.
159e0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 ** a NULL value
159f0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 in place of the
15a00 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 table column tha
15a10 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 t would have.**
15a20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 been read if [SQ
15a30 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 LITE_OK] had bee
15a40 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 n returned. The
15a50 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
15a60 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 .** return can b
15a70 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 e used to deny a
15a80 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 n untrusted user
15a90 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 access to indiv
15aa0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 idual.** columns
15ab0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 of a table..**
15ac0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f If the action co
15ad0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 de is [SQLITE_DE
15ae0 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 LETE] and the ca
15af0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a llback returns.*
15b00 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 * [SQLITE_IGNORE
15b10 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 ] then the [DELE
15b20 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 TE] operation pr
15b30 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a oceeds but the.*
15b40 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 * [truncate opti
15b50 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 mization] is dis
15b60 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f abled and all ro
15b70 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 ws are deleted i
15b80 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a ndividually..**.
15b90 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 ** An authorizer
15ba0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 is used when [s
15bb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
15bc0 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 preparing].** S
15bd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 QL statements fr
15be0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 om an untrusted
15bf0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 source, to ensur
15c00 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 e that the SQL s
15c10 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 tatements.** do
15c20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 not try to acces
15c30 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 s data they are
15c40 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 not allowed to s
15c50 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 ee, or that they
15c60 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 do not.** try t
15c70 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 o execute malici
15c80 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 ous statements t
15c90 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 hat damage the d
15ca0 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a atabase. For.**
15cb0 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
15cc0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c lication may all
15cd0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 ow a user to ent
15ce0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 er arbitrary.**
15cf0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 SQL queries for
15d00 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 evaluation by a
15d10 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 database. But t
15d20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
15d30 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 oes.** not want
15d40 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 the user to be a
15d50 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 ble to make arbi
15d60 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f trary changes to
15d70 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
15d80 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 . An authorizer
15d90 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 could then be p
15da0 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c ut in place whil
15db0 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e e the.** user-en
15dc0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 tered SQL is bei
15dd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
15de0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 are | prepared]
15df0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 that.** disallow
15e00 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 s everything exc
15e10 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 ept [SELECT] sta
15e20 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 tements..**.** A
15e30 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
15e40 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 need to process
15e50 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 SQL from untrus
15e60 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d ted sources.** m
15e70 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 ight also consid
15e80 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f er lowering reso
15e90 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e urce limits usin
15ea0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 g [sqlite3_limit
15eb0 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 ()].** and limit
15ec0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a ing database siz
15ed0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 e using the [max
15ee0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
15ef0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 AGMA].** in addi
15f00 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e tion to using an
15f10 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a authorizer..**.
15f20 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 ** Only a single
15f30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 authorizer can
15f40 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 be in place on a
15f50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
15f60 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d tion.** at a tim
15f70 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f e. Each call to
15f80 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
15f90 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 horizer override
15fa0 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 s the.** previou
15fb0 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 s call. Disable
15fc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
15fd0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 by installing a
15fe0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a NULL callback..*
15ff0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
16000 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
16010 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 default..**.** T
16020 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
16030 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 llback must not
16040 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
16050 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
16060 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
16070 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
16080 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 oked the authori
16090 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a zer callback..**
160a0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
160b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
160c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
160d0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
160e0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
160f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
16100 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
16110 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
16120 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
16130 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 **.** When [sqli
16140 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
16150 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 ] is used to pre
16160 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
16170 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 , the.** stateme
16180 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 nt might be re-p
16190 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b repared during [
161a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
161b0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 due to a .** sch
161c0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e ema change. Hen
161d0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ce, the applicat
161e0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 ion should ensur
161f0 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f e that the.** co
16200 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 rrect authorizer
16210 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e callback remain
16220 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e s in place durin
16230 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 g the [sqlite3_s
16240 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f tep()]..**.** No
16250 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 te that the auth
16260 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
16270 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 is invoked only
16280 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 during.** [sqlit
16290 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
162a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 its variants.
162b0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 Authorization is
162c0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 not.** performe
162d0 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 d during stateme
162e0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e nt evaluation in
162f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
16300 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 ], unless.** as
16310 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 stated in the pr
16320 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 evious paragraph
16330 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 , sqlite3_step()
16340 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 invokes.** sqli
16350 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
16360 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 to reprepare a
16370 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 statement after
16380 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e a schema change.
16390 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
163a0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 30 31 5d nts:.** [H12501]
163b0 20 5b 48 31 32 35 30 32 5d 20 5b 48 31 32 35 30 [H12502] [H1250
163c0 33 5d 20 5b 48 31 32 35 30 34 5d 20 5b 48 31 32 3] [H12504] [H12
163d0 35 30 35 5d 20 5b 48 31 32 35 30 36 5d 20 5b 48 505] [H12506] [H
163e0 31 32 35 30 37 5d 20 5b 48 31 32 35 31 30 5d 0a 12507] [H12510].
163f0 2a 2a 20 5b 48 31 32 35 31 31 5d 20 5b 48 31 32 ** [H12511] [H12
16400 35 31 32 5d 20 5b 48 31 32 35 32 30 5d 20 5b 48 512] [H12520] [H
16410 31 32 35 32 31 5d 20 5b 48 31 32 35 32 32 5d 0a 12521] [H12522].
16420 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
16430 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 t sqlite3_set_au
16440 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 thorizer(. sqli
16450 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 te3*,. int (*xA
16460 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 uth)(void*,int,c
16470 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
16480 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
16490 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c r*,const char*),
164a0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 . void *pUserDa
164b0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ta.);../*.** CAP
164c0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 I3REF: Authorize
164d0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b r Return Codes {
164e0 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e H12590} <H12500>
164f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
16500 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
16510 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
16520 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
16530 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 n] must.** retur
16540 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 n either [SQLITE
16550 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 _OK] or one of t
16560 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e hese two constan
16570 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 ts in order.** t
16580 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 o signal SQLite
16590 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
165a0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 he action is per
165b0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 mitted. See the
165c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 .** [sqlite3_set
165d0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
165e0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e thorizer documen
165f0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 tation] for addi
16600 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
16610 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e ation..*/.#defin
16620 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 e SQLITE_DENY
16630 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 1 /* Abort the
16640 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 SQL statement w
16650 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a ith an error */.
16660 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
16670 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e GNORE 2 /* Don
16680 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 't allow access,
16690 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 but don't gener
166a0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a ate an error */.
166b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
166c0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 Authorizer Acti
166d0 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 on Codes {H12550
166e0 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a } <H12500>.**.**
166f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
16700 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
16710 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
16720 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
16730 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 unction.** that
16740 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 is invoked to au
16750 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 thorize certain
16760 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
16770 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
16780 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
16790 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
167a0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
167b0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
167c0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
167d0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
167e0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
167f0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
16800 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
16810 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
16820 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
16830 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
16840 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
16850 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
16860 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
16870 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a ration is to be.
16880 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ** authorized.
16890 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
168a0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
168b0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a e authorization.
168c0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
168d0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 tion will be par
168e0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 ameters or NULL
168f0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 depending on whi
16900 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 ch of these.** c
16910 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 odes is used as
16920 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
16930 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 eter. The 5th p
16940 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a arameter to the.
16950 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 ** authorizer ca
16960 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 llback is the na
16970 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
16980 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d se ("main", "tem
16990 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 p",.** etc.) if
169a0 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 applicable. The
169b0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6th parameter t
169c0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
169d0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
169e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
169f0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
16a00 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
16a10 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
16a20 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 or.** the access
16a30 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c attempt or NULL
16a40 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 if this access
16a50 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 attempt is direc
16a60 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d tly from.** top-
16a70 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a level SQL code..
16a80 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
16a90 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 35 31 5d 20 ts:.** [H12551]
16aa0 5b 48 31 32 35 35 32 5d 20 5b 48 31 32 35 35 33 [H12552] [H12553
16ab0 5d 20 5b 48 31 32 35 35 34 5d 0a 2a 2f 0a 2f 2a ] [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 20 33 72 64 20 2a ********** 3rd *
16af0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 *********** 4th
16b00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 ***********/.#de
16b10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
16b20 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 TE_INDEX
16b30 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 1 /* Index N
16b40 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
16b50 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
16b60 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
16b70 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 E_TABLE
16b80 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 2 /* Table Na
16b90 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
16ba0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
16bb0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
16bc0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
16bd0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 3 /* Index Nam
16be0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
16bf0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
16c00 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
16c10 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 TEMP_TABLE 4
16c20 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
16c30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
16c40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
16c50 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
16c60 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 EMP_TRIGGER 5
16c70 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
16c80 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
16c90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
16ca0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
16cb0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 MP_VIEW 6
16cc0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
16cd0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
16ce0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
16cf0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 QLITE_CREATE_TRI
16d00 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 GGER 7
16d10 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
16d20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
16d30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
16d40 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 LITE_CREATE_VIEW
16d50 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 8 /
16d60 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
16d70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
16d80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
16d90 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 ITE_DELETE
16da0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 9 /*
16db0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
16dc0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
16dd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16de0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 TE_DROP_INDEX
16df0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 10 /*
16e00 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
16e10 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
16e20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16e30 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 E_DROP_TABLE
16e40 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 11 /* T
16e50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
16e60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
16e70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16e80 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 _DROP_TEMP_INDEX
16e90 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 12 /* In
16ea0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
16eb0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
16ec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16ed0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 DROP_TEMP_TABLE
16ee0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 13 /* Tab
16ef0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
16f00 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
16f10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
16f20 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ROP_TEMP_TRIGGER
16f30 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 14 /* Trig
16f40 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
16f50 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
16f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
16f70 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 OP_TEMP_VIEW
16f80 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 15 /* View
16f90 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
16fa0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
16fb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
16fc0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 P_TRIGGER
16fd0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 16 /* Trigge
16fe0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
16ff0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
17000 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
17010 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
17020 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 17 /* View Na
17030 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
17040 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
17050 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 ine SQLITE_INSER
17060 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
17070 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 18 /* Table Na
17080 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
17090 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
170a0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 ne SQLITE_PRAGMA
170b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
170c0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 9 /* Pragma Na
170d0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f me 1st arg o
170e0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e r NULL */.#defin
170f0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 e SQLITE_READ
17100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20
17110 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
17120 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
17130 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
17140 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 SQLITE_SELECT
17150 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 21
17160 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
17170 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
17180 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
17190 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 SQLITE_TRANSACTI
171a0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 ON 22
171b0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
171c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
171d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
171e0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 QLITE_UPDATE
171f0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 23
17200 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
17210 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
17220 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17230 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 LITE_ATTACH
17240 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 24 /
17250 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 * Filename
17260 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
17270 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
17280 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 ITE_DETACH
17290 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 25 /*
172a0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
172b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
172c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
172d0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 TE_ALTER_TABLE
172e0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 26 /*
172f0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
17300 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
17310 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17320 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 E_REINDEX
17330 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 27 /* I
17340 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e ndex Name N
17350 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
17360 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17370 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 _ANALYZE
17380 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 28 /* Ta
17390 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
173a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
173b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
173c0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 CREATE_VTABLE
173d0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 29 /* Tab
173e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
173f0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
17400 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
17410 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ROP_VTABLE
17420 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 30 /* Tabl
17430 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
17440 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
17450 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
17460 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 NCTION
17470 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 31 /* NULL
17480 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 Funct
17490 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 ion Name */.#d
174a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 efine SQLITE_SAV
174b0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 EPOINT
174c0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 32 /* Operat
174d0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f ion Savepo
174e0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 int Name */.#de
174f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 fine SQLITE_COPY
17500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
17510 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 0 /* No long
17520 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a er used */../*.*
17530 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 * CAPI3REF: Trac
17540 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e ing And Profilin
17550 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 g Functions {H12
17560 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 280} <S60400>.**
17570 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
17580 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
17590 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c es register call
175a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 back functions t
175b0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 hat can be used
175c0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 for.** tracing a
175d0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 nd profiling the
175e0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 execution of SQ
175f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
17600 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b .** The callback
17610 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
17620 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ered by sqlite3_
17630 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b trace() is invok
17640 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 ed at.** various
17650 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 times when an S
17660 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 QL statement is
17670 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 being run by [sq
17680 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
17690 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 * The callback r
176a0 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 eturns a UTF-8 r
176b0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
176c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
176d0 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 xt.** as the sta
176e0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 tement first beg
176f0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 ins executing.
17700 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 Additional callb
17710 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 acks occur.** as
17720 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 each triggered
17730 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e subprogram is en
17740 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c tered. The call
17750 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 backs for trigge
17760 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 rs.** contain a
17770 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e UTF-8 SQL commen
17780 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 t that identifie
17790 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a s the trigger..*
177a0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 *.** The callbac
177b0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
177c0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
177d0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e _profile() is in
177e0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 voked.** as each
177f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
17800 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72 inishes. The pr
17810 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 ofile callback c
17820 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f ontains.** the o
17830 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e riginal statemen
17840 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 t text and an es
17850 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 timate of wall-c
17860 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 lock time.** of
17870 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 how long that st
17880 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 atement took to
17890 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 run..**.** Requi
178a0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
178b0 32 38 31 5d 20 5b 48 31 32 32 38 32 5d 20 5b 48 281] [H12282] [H
178c0 31 32 32 38 33 5d 20 5b 48 31 32 32 38 34 5d 20 12283] [H12284]
178d0 5b 48 31 32 32 38 35 5d 20 5b 48 31 32 32 38 37 [H12285] [H12287
178e0 5d 20 5b 48 31 32 32 38 38 5d 20 5b 48 31 32 32 ] [H12288] [H122
178f0 38 39 5d 0a 2a 2a 20 5b 48 31 32 32 39 30 5d 0a 89].** [H12290].
17900 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
17910 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
17920 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f L void *sqlite3_
17930 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 trace(sqlite3*,
17940 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f void(*xTrace)(vo
17950 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 id*,const char*)
17960 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 , void*);.SQLITE
17970 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 _API SQLITE_EXPE
17980 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 RIMENTAL void *s
17990 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 qlite3_profile(s
179a0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 qlite3*,. void
179b0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 (*xProfile)(void
179c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 *,const char*,sq
179d0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 lite3_uint64), v
179e0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
179f0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 PI3REF: Query Pr
17a00 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 ogress Callbacks
17a10 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30 {H12910} <S6040
17a20 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 0>.**.** This ro
17a30 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 utine configures
17a40 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
17a50 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 tion - the.** pr
17a60 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
17a70 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 - that is invoke
17a80 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 d periodically d
17a90 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 uring long.** ru
17aa0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b nning calls to [
17ab0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c sqlite3_exec()],
17ac0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
17ad0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
17ae0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 3_get_table()].
17af0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 An example use
17b00 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 for this.** inte
17b10 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 rface is to keep
17b20 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 a GUI updated d
17b30 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 uring a large qu
17b40 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ery..**.** If th
17b50 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
17b60 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
17b70 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 zero, the operat
17b80 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 ion is.** interr
17b90 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 upted. This fea
17ba0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 ture can be used
17bb0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a to implement a.
17bc0 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 ** "Cancel" butt
17bd0 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 on on a GUI prog
17be0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e ress dialog box.
17bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 .**.** The progr
17c00 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 ess handler must
17c10 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
17c20 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
17c30 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
17c40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
17c50 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 t invoked the pr
17c60 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a ogress handler..
17c70 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
17c80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
17c90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
17ca0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
17cb0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
17cc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
17cd0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
17ce0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
17cf0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
17d00 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
17d10 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 31 31 ents:.** [H12911
17d20 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48 31 32 39 ] [H12912] [H129
17d30 31 33 5d 20 5b 48 31 32 39 31 34 5d 20 5b 48 31 13] [H12914] [H1
17d40 32 39 31 35 5d 20 5b 48 31 32 39 31 36 5d 20 5b 2915] [H12916] [
17d50 48 31 32 39 31 37 5d 20 5b 48 31 32 39 31 38 5d H12917] [H12918]
17d60 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 .**.*/.SQLITE_AP
17d70 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 I void sqlite3_p
17d80 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
17d90 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 sqlite3*, int, i
17da0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f nt(*)(void*), vo
17db0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
17dc0 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 I3REF: Opening A
17dd0 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f New Database Co
17de0 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 nnection {H12700
17df0 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S40200>.**.**
17e00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
17e10 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 open an SQLite d
17e20 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f atabase file who
17e30 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e se name is given
17e40 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e by the.** filen
17e50 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 ame argument. Th
17e60 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
17e70 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 ent is interpret
17e80 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a ed as UTF-8 for.
17e90 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
17ea0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
17eb0 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 en_v2() and as U
17ec0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
17ed0 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 ive byte.** orde
17ee0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 r for sqlite3_op
17ef0 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 en16(). A [datab
17f00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
17f10 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c handle is usuall
17f20 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e y.** returned in
17f30 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 *ppDb, even if
17f40 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e an error occurs.
17f50 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 The only excep
17f60 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 tion is that.**
17f70 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 if SQLite is una
17f80 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
17f90 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
17fa0 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
17fb0 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 ect,.** a NULL w
17fc0 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 ill be written i
17fd0 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 nto *ppDb instea
17fe0 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 d of a pointer t
17ff0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a o the [sqlite3].
18000 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 ** object. If th
18010 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
18020 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 ened (and/or cre
18030 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c ated) successful
18040 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c ly, then.** [SQL
18050 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 ITE_OK] is retur
18060 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 ned. Otherwise
18070 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
18080 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 is returned. Th
18090 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 e.** [sqlite3_er
180a0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 rmsg()] or [sqli
180b0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 te3_errmsg16()]
180c0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 routines can be
180d0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a used to obtain.*
180e0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e * an English lan
180f0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f guage descriptio
18100 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a n of the error..
18110 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c **.** The defaul
18120 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 t encoding for t
18130 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c he database will
18140 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 be UTF-8 if.**
18150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
18160 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
18170 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 2() is called an
18180 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 d.** UTF-16 in t
18190 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f he native byte o
181a0 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f rder if sqlite3_
181b0 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 open16() is used
181c0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 ..**.** Whether
181d0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 or not an error
181e0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 occurs when it i
181f0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 s opened, resour
18200 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ces.** associate
18210 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 d with the [data
18220 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
18230 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 handle should b
18240 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a e released by.**
18250 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
18260 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
18270 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c when it is no l
18280 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a onger required..
18290 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
182a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 3_open_v2() inte
182b0 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 rface works like
182c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a sqlite3_open().
182d0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 ** except that i
182e0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 t accepts two ad
182f0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 ditional paramet
18300 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ers for addition
18310 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 al control.** ov
18320 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 er the new datab
18330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 ase connection.
18340 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d The flags param
18350 65 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e eter can take on
18360 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c e of.** the foll
18370 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 owing three valu
18380 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 es, optionally c
18390 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 ombined with the
183a0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 .** [SQLITE_OPE
183b0 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c N_NOMUTEX], [SQL
183c0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
183d0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 EX], [SQLITE_OPE
183e0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a N_SHAREDCACHE],.
183f0 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 ** and/or [SQLIT
18400 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
18410 43 48 45 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a CHE] flags:.**.*
18420 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 * <dl>.** <dt>[S
18430 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
18440 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NLY]</dt>.** <dd
18450 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
18460 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d opened in read-
18470 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 only mode. If t
18480 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 he database does
18490 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 not.** already
184a0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 exist, an error
184b0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
184c0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c >.**.** <dt>[SQL
184d0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
184e0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
184f0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
18500 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
18510 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 ng and writing i
18520 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 f possible, or r
18530 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 eading.** only i
18540 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 f the file is wr
18550 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
18560 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
18570 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 ystem. In eithe
18580 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 r.** case the da
18590 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 tabase must alre
185a0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 ady exist, other
185b0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 wise an error is
185c0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a returned.</dd>.
185d0 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 **.** <dt>[SQLIT
185e0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
185f0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ] | [SQLITE_OPEN
18600 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a _CREATE]</dt>.**
18610 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
18620 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
18630 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 reading and writ
18640 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 ing, and is crea
18650 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 tes it if.** it
18660 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 does not already
18670 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 exist. This is
18680 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 the behavior tha
18690 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 t is always used
186a0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
186b0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
186c0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 e3_open16().</dd
186d0 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a >.** </dl>.**.**
186e0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
186f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
18700 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f _open_v2() is no
18710 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 t one of the.**
18720 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f combinations sho
18730 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 wn above or one
18740 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 of the combinati
18750 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 ons shown above
18760 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 combined.** with
18770 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
18780 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c N_NOMUTEX], [SQL
18790 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
187a0 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f EX],.** [SQLITE_
187b0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
187c0 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 ] and/or [SQLITE
187d0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
187e0 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 E] flags,.** the
187f0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
18800 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
18810 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 ** If the [SQLIT
18820 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 E_OPEN_NOMUTEX]
18830 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 flag is set, the
18840 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
18850 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 onnection.** ope
18860 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d ns in the multi-
18870 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
18880 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 g mode] as long
18890 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 as the single-th
188a0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 read.** mode has
188b0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 not been set at
188c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
188d0 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 start-time. If
188e0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
188f0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 OPEN_FULLMUTEX]
18900 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e flag is set then
18910 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
18920 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a nnection opens.*
18930 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 * in the seriali
18940 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
18950 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 ode] unless sing
18960 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a le-thread was.**
18970 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 previously sele
18980 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d cted at compile-
18990 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 time or start-ti
189a0 6d 65 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 me..** The [SQLI
189b0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
189c0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 CHE] flag causes
189d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
189e0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a nnection to be.*
189f0 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 * eligible to us
18a00 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 e [shared cache
18a10 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 mode], regardles
18a20 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
18a30 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 not shared.** ca
18a40 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 che is enabled u
18a50 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e sing [sqlite3_en
18a60 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
18a70 65 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 53 e()]. The.** [S
18a80 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
18a90 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 TECACHE] flag ca
18aa0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 uses the databas
18ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 e connection to
18ac0 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 not.** participa
18ad0 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 te in [shared ca
18ae0 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 che mode] even i
18af0 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e f it is enabled.
18b00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 .**.** If the fi
18b10 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f lename is ":memo
18b20 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 ry:", then a pri
18b30 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 vate, temporary
18b40 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
18b50 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 se.** is created
18b60 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 for the connect
18b70 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 ion. This in-me
18b80 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 mory database wi
18b90 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a ll vanish when.*
18ba0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
18bb0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
18bc0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 sed. Future ver
18bd0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
18be0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 might.** make us
18bf0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 e of additional
18c00 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 special filename
18c10 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 s that begin wit
18c20 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 h the ":" charac
18c30 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 ter..** It is re
18c40 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 commended that w
18c50 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 hen a database f
18c60 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 ilename actually
18c70 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 does begin with
18c80 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 .** a ":" charac
18c90 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 ter you should p
18ca0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 refix the filena
18cb0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 me with a pathna
18cc0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e me such as.** ".
18cd0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 /" to avoid ambi
18ce0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 guity..**.** If
18cf0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
18d00 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
18d10 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
18d20 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e temporary.** on
18d30 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 -disk database w
18d40 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 ill be created.
18d50 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 This private da
18d60 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a tabase will be.*
18d70 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
18d80 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 deleted as soon
18d90 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 as the database
18da0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
18db0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 osed..**.** The
18dc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
18dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
18de0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d _v2() is the nam
18df0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c e of the.** [sql
18e00 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
18e10 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 that defines th
18e20 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
18e30 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
18e40 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 t.** the new dat
18e50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18e60 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 should use. If
18e70 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
18e80 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 meter is.** a NU
18e90 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
18ea0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
18eb0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
18ec0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
18ed0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f <b>Note to Windo
18ee0 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 ws users:</b> T
18ef0 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 he encoding used
18f00 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d for the filenam
18f10 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 e argument.** of
18f20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
18f30 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
18f40 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 _v2() must be UT
18f50 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 F-8, not whateve
18f60 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 r.** codepage is
18f70 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
18f80 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 ed. Filenames c
18f90 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e ontaining intern
18fa0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 ational.** chara
18fb0 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f cters must be co
18fc0 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 nverted to UTF-8
18fd0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e prior to passin
18fe0 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 g them into.** s
18ff0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
19000 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
19010 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ()..**.** Requir
19020 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 ements:.** [H127
19030 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 31 01] [H12702] [H1
19040 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b 2703] [H12704] [
19050 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37 5d H12706] [H12707]
19060 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37 31 [H12709] [H1271
19070 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b 1].** [H12712] [
19080 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34 5d H12713] [H12714]
19090 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37 31 [H12717] [H1271
190a0 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 32 9] [H12721] [H12
190b0 37 32 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 723].*/.SQLITE_A
190c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f PI int sqlite3_o
190d0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 pen(. const cha
190e0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
190f0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
19100 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
19110 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
19120 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
19130 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
19140 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 e */.);.SQLITE_A
19150 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f PI int sqlite3_o
19160 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 pen16(. const v
19170 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 oid *filename,
19180 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
19190 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a ename (UTF-16) *
191a0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
191b0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
191c0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
191d0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 ndle */.);.SQLIT
191e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
191f0 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 3_open_v2(. con
19200 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d st char *filenam
19210 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 e, /* Database
19220 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 filename (UTF-8
19230 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a ) */. sqlite3 *
19240 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f *ppDb, /
19250 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 * OUT: SQLite db
19260 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 handle */. int
19270 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 flags,
19280 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f /* Flags */
19290 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
192a0 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 Vfs /* Na
192b0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 me of VFS module
192c0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f to use */.);../
192d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
192e0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d rror Codes And M
192f0 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d essages {H12800}
19300 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S60200>.**.**
19310 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 The sqlite3_errc
19320 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ode() interface
19330 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 returns the nume
19340 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 ric [result code
19350 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
19360 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 d result code] f
19370 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 or the most rece
19380 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 nt failed sqlite
19390 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 3_* API call.**
193a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
193b0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
193c0 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 ection]. If a pr
193d0 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 ior API call fai
193e0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d led.** but the m
193f0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 ost recent API c
19400 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 all succeeded, t
19410 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
19420 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f from.** sqlite3_
19430 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 errcode() is und
19440 65 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c efined. The sql
19450 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 ite3_extended_er
19460 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 rcode().** inter
19470 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 face is the same
19480 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
19490 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 always returns t
194a0 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 he .** [extended
194b0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 result code] ev
194c0 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 en when extended
194d0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
194e0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a e.** disabled..*
194f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
19500 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 _errmsg() and sq
19510 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
19520 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d return English-
19530 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 language.** text
19540 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 that describes
19550 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 the error, as ei
19560 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
19570 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c F-16 respectivel
19580 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 y..** Memory to
19590 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d hold the error m
195a0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
195b0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 managed interna
195c0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c lly..** The appl
195d0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ication does not
195e0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 need to worry a
195f0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 bout freeing the
19600 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 result..** Howe
19610 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 ver, the error s
19620 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f tring might be o
19630 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 verwritten or de
19640 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 allocated by.**
19650 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
19660 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 to other SQLite
19670 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 interface funct
19680 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ions..**.** When
19690 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 the serialized
196a0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
196b0 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d is in use, it m
196c0 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 ight be the.** c
196d0 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e ase that a secon
196e0 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f d error occurs o
196f0 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 n a separate thr
19700 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a ead in between.*
19710 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 * the time of th
19720 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e e first error an
19730 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 d the call to th
19740 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a ese interfaces..
19750 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 ** When that hap
19760 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 pens, the second
19770 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 error will be r
19780 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 eported since th
19790 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ese.** interface
197a0 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 s always report
197b0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
197c0 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 result. To avoi
197d0 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 d.** this, each
197e0 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 thread can obtai
197f0 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 n exclusive use
19800 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
19810 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a connection] D.*
19820 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 * by invoking [s
19830 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 qlite3_mutex_ent
19840 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f er]([sqlite3_db_
19850 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 mutex](D)) befor
19860 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 e beginning.** t
19870 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f o use D and invo
19880 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
19890 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 tex_leave]([sqli
198a0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
198b0 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 ) after.** all c
198c0 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 alls to the inte
198d0 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 rfaces listed he
198e0 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 re are completed
198f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e ..**.** If an in
19900 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 terface fails wi
19910 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 th SQLITE_MISUSE
19920 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 , that means the
19930 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 interface.** wa
19940 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 s invoked incorr
19950 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 ectly by the app
19960 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 lication. In th
19970 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 at case, the.**
19980 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d error code and m
19990 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 essage may or ma
199a0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a y not be set..**
199b0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
199c0 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48 :.** [H12801] [H
199d0 31 32 38 30 32 5d 20 5b 48 31 32 38 30 33 5d 20 12802] [H12803]
199e0 5b 48 31 32 38 30 37 5d 20 5b 48 31 32 38 30 38 [H12807] [H12808
199f0 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 53 51 ] [H12809].*/.SQ
19a00 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
19a10 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c ite3_errcode(sql
19a20 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 ite3 *db);.SQLIT
19a30 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
19a40 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
19a50 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
19a60 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
19a70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
19a80 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 errmsg(sqlite3*)
19a90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
19aa0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
19ab0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 _errmsg16(sqlite
19ac0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
19ad0 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 3REF: SQL Statem
19ae0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 ent Object {H130
19af0 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 00} <H13010>.**
19b00 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 KEYWORDS: {prepa
19b10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b red statement} {
19b20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
19b30 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e nts}.**.** An in
19b40 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
19b50 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
19b60 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 a single SQL st
19b70 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 atement..** This
19b80 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f object is vario
19b90 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 usly known as a
19ba0 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d "prepared statem
19bb0 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f ent" or a.** "co
19bc0 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 mpiled SQL state
19bd0 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 ment" or simply
19be0 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 as a "statement"
19bf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 ..**.** The life
19c00 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 of a statement
19c10 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 object goes some
19c20 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a thing like this:
19c30 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c .**.** <ol>.** <
19c40 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f li> Create the o
19c50 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c bject using [sql
19c60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
19c70 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a )] or a related.
19c80 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e ** function
19c90 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 ..** <li> Bind v
19ca0 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 alues to [host p
19cb0 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 arameters] using
19cc0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
19cd0 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e d_*().** in
19ce0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 terfaces..** <li
19cf0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 > Run the SQL by
19d00 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
19d10 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 3_step()] one or
19d20 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
19d30 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 <li> Reset the s
19d40 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
19d50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
19d60 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a then go back.**
19d70 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e to step 2.
19d80 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f Do this zero o
19d90 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a r more times..**
19da0 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 <li> Destroy th
19db0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
19dc0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
19dd0 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a ()]..** </ol>.**
19de0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 .** Refer to doc
19df0 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e umentation on in
19e00 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 dividual methods
19e10 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 above for addit
19e20 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ional.** informa
19e30 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
19e40 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
19e50 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d stmt sqlite3_stm
19e60 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 t;../*.** CAPI3R
19e70 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d EF: Run-time Lim
19e80 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 its {H12760} <S2
19e90 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0600>.**.** This
19ea0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 interface allow
19eb0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 s the size of va
19ec0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 rious constructs
19ed0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a to be limited.*
19ee0 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f * on a connectio
19ef0 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 n by connection
19f00 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 basis. The firs
19f10 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
19f20 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 he.** [database
19f30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 connection] whos
19f40 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 e limit is to be
19f50 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e set or queried.
19f60 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 The.** second
19f70 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 parameter is one
19f80 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 of the [limit c
19f90 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 ategories] that
19fa0 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 define a.** clas
19fb0 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 s of constructs
19fc0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 to be size limit
19fd0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 ed. The third p
19fe0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
19ff0 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 ** new limit for
1a000 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e that construct.
1a010 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 The function r
1a020 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c eturns the old l
1a030 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 imit..**.** If t
1a040 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 he new limit is
1a050 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 a negative numbe
1a060 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 r, the limit is
1a070 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f unchanged..** Fo
1a080 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 r the limit cate
1a090 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c gory of SQLITE_L
1a0a0 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 IMIT_XYZ there i
1a0b0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 s a .** [limits
1a0c0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 | hard upper bou
1a0d0 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 nd].** set by a
1a0e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 compile-time C p
1a0f0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
1a100 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d o named .** [lim
1a110 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 its | SQLITE_MAX
1a120 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 _XYZ]..** (The "
1a130 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 _LIMIT_" in the
1a140 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 name is changed
1a150 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 to "_MAX_".).**
1a160 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 Attempts to incr
1a170 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f ease a limit abo
1a180 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 ve its hard uppe
1a190 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 r bound are.** s
1a1a0 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 ilently truncate
1a1b0 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 d to the hard up
1a1c0 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a per limit..**.**
1a1d0 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 Run time limits
1a1e0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
1a1f0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 r use in applica
1a200 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 tions that manag
1a210 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 e.** both their
1a220 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 own internal dat
1a230 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 abase and also d
1a240 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 atabases that ar
1a250 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 e controlled.**
1a260 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 by untrusted ext
1a270 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 ernal sources.
1a280 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 An example appli
1a290 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 cation might be
1a2a0 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 a.** web browser
1a2b0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 that has its ow
1a2c0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 n databases for
1a2d0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 storing history
1a2e0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 and.** separate
1a2f0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f databases contro
1a300 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 lled by JavaScri
1a310 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 pt applications
1a320 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 downloaded.** of
1a330 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 f the Internet.
1a340 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 The internal da
1a350 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 tabases can be g
1a360 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 iven the.** larg
1a370 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 e, default limit
1a380 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 s. Databases ma
1a390 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 naged by externa
1a3a0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a l sources can.**
1a3b0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 be given much s
1a3c0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 maller limits de
1a3d0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e signed to preven
1a3e0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 t a denial of se
1a3f0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e rvice.** attack.
1a400 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 Developers mig
1a410 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 ht also want to
1a420 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 use the [sqlite3
1a430 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1a440 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 )].** interface
1a450 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 to further contr
1a460 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c ol untrusted SQL
1a470 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 . The size of t
1a480 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
1a490 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 reated by an unt
1a4a0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 rusted script ca
1a4b0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 n be contained u
1a4c0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 sing the.** [max
1a4d0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
1a4e0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 AGMA]..**.** New
1a4f0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 run-time limit
1a500 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 categories may b
1a510 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
1a520 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a e releases..**.*
1a530 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
1a540 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b 48 31 32 ** [H12762] [H12
1a550 37 36 36 5d 20 5b 48 31 32 37 36 39 5d 0a 2a 2f 766] [H12769].*/
1a560 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1a570 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 sqlite3_limit(sq
1a580 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 lite3*, int id,
1a590 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a int newVal);../*
1a5a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 .** CAPI3REF: Ru
1a5b0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 n-Time Limit Cat
1a5c0 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d egories {H12790}
1a5d0 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 <H12760>.** KEY
1a5e0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 WORDS: {limit ca
1a5f0 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 tegory} {limit c
1a600 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a ategories}.**.**
1a610 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
1a620 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 define various
1a630 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 performance limi
1a640 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 ts.** that can b
1a650 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e e lowered at run
1a660 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c -time using [sql
1a670 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a ite3_limit()]..*
1a680 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f * The synopsis o
1a690 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f f the meanings o
1a6a0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 f the various li
1a6b0 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 mits is shown be
1a6c0 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e low..** Addition
1a6d0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 al information i
1a6e0 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b s available at [
1a6f0 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 limits | Limits
1a700 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a in SQLite]..**.*
1a710 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 * <dl>.** <dt>SQ
1a720 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
1a730 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
1a740 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f e maximum size o
1a750 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 f any string or
1a760 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f BLOB or table ro
1a770 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 w.<dd>.**.** <dt
1a780 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 >SQLITE_LIMIT_SQ
1a790 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a L_LENGTH</dt>.**
1a7a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1a7b0 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 length of an SQ
1a7c0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 L statement.</dd
1a7d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
1a7e0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c TE_LIMIT_COLUMN<
1a7f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1a800 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
1a810 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 f columns in a t
1a820 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 able definition
1a830 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 or in the.** res
1a840 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
1a850 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 LECT] or the max
1a860 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
1a870 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 olumns in an ind
1a880 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f ex.** or in an O
1a890 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 RDER BY or GROUP
1a8a0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e BY clause.</dd>
1a8b0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
1a8c0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
1a8d0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
1a8e0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 he maximum depth
1a8f0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 of the parse tr
1a900 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 ee on any expres
1a910 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a sion.</dd>.**.**
1a920 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
1a930 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
1a940 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 T</dt>.** <dd>Th
1a950 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
1a960 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 of terms in a c
1a970 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 ompound SELECT s
1a980 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a tatement.</dd>.*
1a990 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
1a9a0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 LIMIT_VDBE_OP</d
1a9b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1a9c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
1a9d0 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 instructions in
1a9e0 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e a virtual machin
1a9f0 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 e program.** use
1aa00 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
1aa10 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e n SQL statement.
1aa20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
1aa30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
1aa40 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a CTION_ARG</dt>.*
1aa50 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1aa60 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 m number of argu
1aa70 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 ments on a funct
1aa80 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
1aa90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
1aaa0 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a _ATTACHED</dt>.*
1aab0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1aac0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 m number of [ATT
1aad0 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 ACH | attached d
1aae0 61 74 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a atabases].</dd>.
1aaf0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
1ab00 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
1ab10 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a ERN_LENGTH</dt>.
1ab20 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1ab30 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 um length of the
1ab40 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e pattern argumen
1ab50 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 t to the [LIKE]
1ab60 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 or.** [GLOB] ope
1ab70 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a rators.</dd>.**.
1ab80 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
1ab90 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
1aba0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e BER</dt>.** <dd>
1abb0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1abc0 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 er of variables
1abd0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d in an SQL statem
1abe0 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 ent that can.**
1abf0 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a be bound.</dd>.*
1ac00 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
1ac10 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 LIMIT_TRIGGER_DE
1ac20 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e PTH</dt>.** <dd>
1ac30 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 The maximum dept
1ac40 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 h of recursion f
1ac50 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 or triggers.</dd
1ac60 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 >.** </dl>.*/.#d
1ac70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
1ac80 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 IT_LENGTH
1ac90 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 0.#
1aca0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
1acb0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 MIT_SQL_LENGTH
1acc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 1.
1acd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1ace0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 IMIT_COLUMN
1acf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
1ad00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ad10 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 LIMIT_EXPR_DEPTH
1ad20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1ad30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
1ad40 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f _LIMIT_COMPOUND_
1ad50 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 SELECT
1ad60 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
1ad70 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 E_LIMIT_VDBE_OP
1ad80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1ad90 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 5.#define SQLI
1ada0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
1adb0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 N_ARG
1adc0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 6.#define SQL
1add0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 ITE_LIMIT_ATTACH
1ade0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ED
1adf0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 7.#define SQ
1ae00 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
1ae10 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 PATTERN_LENGTH
1ae20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 8.#define S
1ae30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
1ae40 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 ABLE_NUMBER
1ae50 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 9.#define
1ae60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 SQLITE_LIMIT_TRI
1ae70 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 GGER_DEPTH
1ae80 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 10../*.**
1ae90 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
1aea0 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 ing An SQL State
1aeb0 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 ment {H13010} <S
1aec0 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 10000>.** KEYWOR
1aed0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 DS: {SQL stateme
1aee0 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a nt compiler}.**.
1aef0 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e ** To execute an
1af00 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d SQL query, it m
1af10 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d ust first be com
1af20 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 piled into a byt
1af30 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 e-code.** progra
1af40 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 m using one of t
1af50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
1af60 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
1af70 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 rgument, "db", i
1af80 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f s a [database co
1af90 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e nnection] obtain
1afa0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 ed from a.** pri
1afb0 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 or successful ca
1afc0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f ll to [sqlite3_o
1afd0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
1afe0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a _open_v2()] or.*
1aff0 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 * [sqlite3_open1
1b000 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 6()]. The datab
1b010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d ase connection m
1b020 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 ust not have bee
1b030 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 n closed..**.**
1b040 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
1b050 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 ent, "zSql", is
1b060 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f the statement to
1b070 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e be compiled, en
1b080 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 coded.** as eith
1b090 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d er UTF-8 or UTF-
1b0a0 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 16. The sqlite3
1b0b0 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 _prepare() and s
1b0c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1b0d0 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2().** interface
1b0e0 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 s use UTF-8, and
1b0f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1b100 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 16() and sqlite3
1b110 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a _prepare16_v2().
1b120 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a ** use UTF-16..*
1b130 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 *.** If the nByt
1b140 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 e argument is le
1b150 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 ss than zero, th
1b160 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 en zSql is read
1b170 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 up to the.** fir
1b180 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
1b190 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 or. If nByte is
1b1a0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
1b1b0 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 en it is the max
1b1c0 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f imum.** number o
1b1d0 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 f bytes read fr
1b1e0 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e om zSql. When n
1b1f0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 Byte is non-nega
1b200 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 tive, the.** zSq
1b210 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 l string ends at
1b220 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 either the firs
1b230 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 t '\000' or '\u0
1b240 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 000' character o
1b250 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 r.** the nByte-t
1b260 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 h byte, whicheve
1b270 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 r comes first. I
1b280 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f f the caller kno
1b290 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 ws.** that the s
1b2a0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 upplied string i
1b2b0 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 s nul-terminated
1b2c0 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 , then there is
1b2d0 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f a small.** perfo
1b2e0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 rmance advantage
1b2f0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 to be gained by
1b300 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 passing an nByt
1b310 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
1b320 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 .** is equal to
1b330 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
1b340 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 tes in the input
1b350 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 string <i>inclu
1b360 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 ding</i>.** the
1b370 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 nul-terminator b
1b380 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 70 ytes..**.** If p
1b390 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c zTail is not NUL
1b3a0 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 L then *pzTail i
1b3b0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 s made to point
1b3c0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 to the first byt
1b3d0 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e e.** past the en
1b3e0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 d of the first S
1b3f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
1b400 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 zSql. These rou
1b410 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f tines only.** co
1b420 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 mpile the first
1b430 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 statement in zSq
1b440 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 l, so *pzTail is
1b450 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
1b460 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e o.** what remain
1b470 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a s uncompiled..**
1b480 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c .** *ppStmt is l
1b490 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 eft pointing to
1b4a0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 a compiled [prep
1b4b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1b4c0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 that can be.** e
1b4d0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 xecuted using [s
1b4e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 qlite3_step()].
1b4f0 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 If there is an
1b500 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 error, *ppStmt i
1b510 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c s set.** to NULL
1b520 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 . If the input
1b530 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f text contains no
1b540 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 SQL (if the inp
1b550 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a ut is an empty.*
1b560 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f * string or a co
1b570 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 mment) then *ppS
1b580 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 tmt is set to NU
1b590 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 LL..** The calli
1b5a0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 ng procedure is
1b5b0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
1b5c0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d deleting the com
1b5d0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 piled.** SQL sta
1b5e0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 tement using [sq
1b5f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
1b600 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 ] after it has f
1b610 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
1b620 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e .** ppStmt may n
1b630 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ot be NULL..**.*
1b640 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 * On success, [S
1b650 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 QLITE_OK] is ret
1b660 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 urned, otherwise
1b670 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
1b680 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
1b690 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1b6a0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 prepare_v2() and
1b6b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1b6c0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 16_v2() interfac
1b6d0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d es are.** recomm
1b6e0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 ended for all ne
1b6f0 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 w programs. The
1b700 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 two older interf
1b710 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 aces are retaine
1b720 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 d.** for backwar
1b730 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
1b740 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 , but their use
1b750 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a is discouraged..
1b760 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 ** In the "v2" i
1b770 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 nterfaces, the p
1b780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1b790 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 t.** that is ret
1b7a0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 urned (the [sqli
1b7b0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
1b7c0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 ) contains a cop
1b7d0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 y of the.** orig
1b7e0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 inal SQL text. T
1b7f0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b his causes the [
1b800 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1b810 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 interface to.**
1b820 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 behave a 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..