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 31 2d 30 34 20 31 33 3a 33 30 2009-11-04 13:30
1170: 3a 30 32 20 65 62 37 61 35 34 34 66 65 34 39 64 :02 eb7a544fe49d
1180: 31 36 32 36 62 61 63 65 63 66 65 35 33 64 64 63 1626bacecfe53ddc
1190: 30 33 66 65 30 38 32 65 33 32 34 33 22 0a 0a 2f 03fe082e3243"../
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 2a 6c 69 6d 69 74 20 tegory} {*limit
1a600 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a categories}.**.*
1a610 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
1a620 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 s define various
1a630 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d performance lim
1a640 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 its.** that can
1a650 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 be lowered at ru
1a660 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 n-time using [sq
1a670 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a lite3_limit()]..
1a680 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 ** The synopsis
1a690 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 of the meanings
1a6a0 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c of the various l
1a6b0 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 imits is shown b
1a6c0 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f elow..** Additio
1a6d0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 nal information
1a6e0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 is available at
1a6f0 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 [limits | Limits
1a700 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a in SQLite]..**.
1a710 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 ** <dl>.** <dt>S
1a720 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
1a730 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
1a740 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 he maximum size
1a750 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 of any string or
1a760 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 BLOB or table r
1a770 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 ow.<dd>.**.** <d
1a780 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 t>SQLITE_LIMIT_S
1a790 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a QL_LENGTH</dt>.*
1a7a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1a7b0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 m length of an S
1a7c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 QL statement.</d
1a7d0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
1a7e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
1a7f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1a800 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1a810 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 of columns in a
1a820 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e table definition
1a830 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 or in the.** re
1a840 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 sult set of a [S
1a850 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 ELECT] or the ma
1a860 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
1a870 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e columns in an in
1a880 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 dex.** or in an
1a890 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 ORDER BY or GROU
1a8a0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 P BY clause.</dd
1a8b0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
1a8c0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 TE_LIMIT_EXPR_DE
1a8d0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e PTH</dt>.** <dd>
1a8e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 The maximum dept
1a8f0 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 h of the parse t
1a900 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 ree on any expre
1a910 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ssion.</dd>.**.*
1a920 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
1a930 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
1a940 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 CT</dt>.** <dd>T
1a950 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
1a960 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 r of terms in a
1a970 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 compound SELECT
1a980 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a statement.</dd>.
1a990 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
1a9a0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f _LIMIT_VDBE_OP</
1a9b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
1a9c0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
1a9d0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e instructions in
1a9e0 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 a virtual machi
1a9f0 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 ne program.** us
1aa00 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 ed to implement
1aa10 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
1aa20 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
1aa30 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 >SQLITE_LIMIT_FU
1aa40 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a NCTION_ARG</dt>.
1aa50 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1aa60 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 um number of arg
1aa70 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 uments on a func
1aa80 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
1aa90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
1aaa0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a T_ATTACHED</dt>.
1aab0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1aac0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 um number of [AT
1aad0 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 TACH | attached
1aae0 64 61 74 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e databases].</dd>
1aaf0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
1ab00 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 E_LIMIT_LIKE_PAT
1ab10 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e TERN_LENGTH</dt>
1ab20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1ab30 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 mum length of th
1ab40 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 e pattern argume
1ab50 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d nt to the [LIKE]
1ab60 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 or.** [GLOB] op
1ab70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a erators.</dd>.**
1ab80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
1ab90 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
1aba0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 MBER</dt>.** <dd
1abb0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
1abc0 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 ber of variables
1abd0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 in an SQL state
1abe0 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a ment that can.**
1abf0 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a be bound.</dd>.
1ac00 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
1ac10 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
1ac20 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
1ac30 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
1ac40 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 th of recursion
1ac50 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 for triggers.</d
1ac60 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 d>.** </dl>.*/.#
1ac70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
1ac80 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 MIT_LENGTH
1ac90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 0.
1aca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1acb0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 IMIT_SQL_LENGTH
1acc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
1acd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ace0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 LIMIT_COLUMN
1acf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1ad00 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
1ad10 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 _LIMIT_EXPR_DEPT
1ad20 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
1ad30 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
1ad40 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 E_LIMIT_COMPOUND
1ad50 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 _SELECT
1ad60 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
1ad70 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 TE_LIMIT_VDBE_OP
1ad80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1ad90 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
1ada0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
1adb0 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 ON_ARG
1adc0 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 6.#define SQ
1add0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
1ade0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 HED
1adf0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 7.#define S
1ae00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 QLITE_LIMIT_LIKE
1ae10 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 _PATTERN_LENGTH
1ae20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
1ae30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
1ae40 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 IABLE_NUMBER
1ae50 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 9.#define
1ae60 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 SQLITE_LIMIT_TR
1ae70 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 IGGER_DEPTH
1ae80 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 10../*.**
1ae90 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
1aea0 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 ling An SQL Stat
1aeb0 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c ement {H13010} <
1aec0 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S10000>.** KEYWO
1aed0 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d RDS: {SQL statem
1aee0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a ent compiler}.**
1aef0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 .** To execute a
1af00 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 n SQL query, it
1af10 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f must first be co
1af20 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 mpiled into a by
1af30 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 te-code.** progr
1af40 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 am using one of
1af50 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
1af60 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
1af70 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 argument, "db",
1af80 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 is a [database c
1af90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 onnection] obtai
1afa0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 ned from a.** pr
1afb0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
1afc0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
1afd0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
1afe0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 3_open_v2()] or.
1aff0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
1b000 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 16()]. The data
1b010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1b020 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 must not have be
1b030 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a en closed..**.**
1b040 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
1b050 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 ment, "zSql", is
1b060 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
1b070 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 o be compiled, e
1b080 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 ncoded.** as eit
1b090 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
1b0a0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 -16. The sqlite
1b0b0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 3_prepare() and
1b0c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1b0d0 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 v2().** interfac
1b0e0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e es use UTF-8, an
1b0f0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
1b100 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 e16() and sqlite
1b110 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
1b120 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a .** use UTF-16..
1b130 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 **.** If the nBy
1b140 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c te argument is l
1b150 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 ess than zero, t
1b160 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 hen zSql is read
1b170 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 up to the.** fi
1b180 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 rst zero termina
1b190 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 tor. If nByte is
1b1a0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
1b1b0 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 hen it is the ma
1b1c0 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 ximum.** number
1b1d0 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 of bytes read f
1b1e0 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 rom zSql. When
1b1f0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 nByte is non-neg
1b200 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 ative, the.** zS
1b210 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 ql string ends a
1b220 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 t either the fir
1b230 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 st '\000' or '\u
1b240 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 0000' character
1b250 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d or.** the nByte-
1b260 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 th byte, whichev
1b270 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 er comes first.
1b280 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e If the caller kn
1b290 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ows.** that the
1b2a0 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 supplied string
1b2b0 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 is nul-terminate
1b2c0 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 d, then there is
1b2d0 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 a small.** perf
1b2e0 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 ormance advantag
1b2f0 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 e to be gained b
1b300 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 y passing an nBy
1b310 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 te parameter tha
1b320 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f t.** is equal to
1b330 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
1b340 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 ytes in the inpu
1b350 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c t string <i>incl
1b360 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 uding</i>.** the
1b370 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 nul-terminator
1b380 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 bytes..**.** If
1b390 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 pzTail is not NU
1b3a0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 LL then *pzTail
1b3b0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
1b3c0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 to the first by
1b3d0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 te.** past the e
1b3e0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 nd of the first
1b3f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
1b400 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f zSql. These ro
1b410 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 utines only.** c
1b420 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 ompile the first
1b430 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
1b440 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 ql, so *pzTail i
1b450 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
1b460 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 to.** what remai
1b470 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a ns uncompiled..*
1b480 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 *.** *ppStmt is
1b490 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f left pointing to
1b4a0 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 a compiled [pre
1b4b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1b4c0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 that can be.**
1b4d0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b executed using [
1b4e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
1b4f0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e If there is an
1b500 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 error, *ppStmt
1b510 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c is set.** to NUL
1b520 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 L. If the input
1b530 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e text contains n
1b540 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e o SQL (if the in
1b550 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a put is an empty.
1b560 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 ** string or a c
1b570 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 omment) then *pp
1b580 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e Stmt is set to N
1b590 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ULL..** The call
1b5a0 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 ing procedure is
1b5b0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
1b5c0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f deleting the co
1b5d0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 mpiled.** SQL st
1b5e0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
1b5f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
1b600 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 )] after it has
1b610 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 finished with it
1b620 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 ..** ppStmt may
1b630 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a not be NULL..**.
1b640 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b ** On success, [
1b650 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 SQLITE_OK] is re
1b660 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 turned, otherwis
1b670 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
1b680 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
1b690 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1b6a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e _prepare_v2() an
1b6b0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
1b6c0 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 e16_v2() interfa
1b6d0 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d ces are.** recom
1b6e0 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e mended for all n
1b6f0 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 ew programs. The
1b700 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 two older inter
1b710 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e faces are retain
1b720 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 ed.** for backwa
1b730 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
1b740 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 y, but their use
1b750 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e is discouraged.
1b760 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 .** In the "v2"
1b770 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 interfaces, the
1b780 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1b790 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 nt.** that is re
1b7a0 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c turned (the [sql
1b7b0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 ite3_stmt] objec
1b7c0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f t) contains a co
1b7d0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 py of the.** ori
1b7e0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 ginal SQL text.
1b7f0 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 This causes the
1b800 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1b810 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a interface to.**
1b820 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72 behave a differ
1b830 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 ently in three w
1b840 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a ays:.**.** <ol>.
1b850 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 ** <li>.** If th
1b860 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
1b870 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 a changes, inste
1b880 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 ad of returning
1b890 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 [SQLITE_SCHEMA]
1b8a0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 as it.** always
1b8b0 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c used to do, [sql
1b8c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
1b8d0 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 l automatically
1b8e0 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 recompile the SQ
1b8f0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 L.** statement a
1b900 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 nd try to run it
1b910 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 again. If the
1b920 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 schema has chang
1b930 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 ed in.** a way t
1b940 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 hat makes the st
1b950 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 atement no longe
1b960 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 r valid, [sqlite
1b970 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 3_step()] will s
1b980 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b till.** return [
1b990 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 SQLITE_SCHEMA].
1b9a0 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 But unlike the
1b9b0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c legacy behavior,
1b9c0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
1b9d0 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 is.** now a fat
1b9e0 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 al error. Calli
1b9f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
1ba00 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 are_v2()] again
1ba10 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 will not make th
1ba20 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 e.** error go aw
1ba30 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b ay. Note: use [
1ba40 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
1ba50 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 ] to find the te
1ba60 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 xt.** of the par
1ba70 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 sing error that
1ba80 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 results in an [S
1ba90 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 QLITE_SCHEMA] re
1baa0 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a turn..** </li>.*
1bab0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 *.** <li>.** Whe
1bac0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 n an error occur
1bad0 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 s, [sqlite3_step
1bae0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ()] will return
1baf0 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 one of the detai
1bb00 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f led.** [error co
1bb10 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 des] or [extende
1bb20 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 d error codes].
1bb30 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 The legacy beha
1bb40 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a vior was that.**
1bb50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1bb60 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 ] would only ret
1bb70 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 urn a generic [S
1bb80 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 QLITE_ERROR] res
1bb90 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 ult code.** and
1bba0 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 you would have t
1bbb0 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 o make a second
1bbc0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
1bbd0 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 _reset()] in ord
1bbe0 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 er.** to find th
1bbf0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 e underlying cau
1bc00 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 se of the proble
1bc10 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 m. With the "v2"
1bc20 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 prepare.** inte
1bc30 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 rfaces, the unde
1bc40 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f rlying reason fo
1bc50 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 r the error is r
1bc60 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 eturned immediat
1bc70 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a ely..** </li>.**
1bc80 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 .** <li>.** ^If
1bc90 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 5b the value of a [
1bca0 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 parameter | host
1bcb0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 parameter] in t
1bcc0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 he WHERE clause
1bcd0 6d 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67 65 20 might.** change
1bce0 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20 66 the query plan f
1bcf0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 or a statement,
1bd00 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 then the stateme
1bd10 6e 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61 75 74 nt may be.** aut
1bd20 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d omatically recom
1bd30 70 69 6c 65 64 20 28 61 73 20 69 66 20 74 68 65 piled (as if the
1bd40 72 65 20 68 61 64 20 62 65 65 6e 20 61 20 73 63 re had been a sc
1bd50 68 65 6d 61 20 63 68 61 6e 67 65 29 20 6f 6e 20 hema change) on
1bd60 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 5b 73 the first .** [s
1bd70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 qlite3_step()] c
1bd80 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e all following an
1bd90 79 20 63 68 61 6e 67 65 20 74 6f 20 74 68 65 20 y change to the
1bda0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
1bdb0 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 d_text | binding
1bdc0 73 5d 20 6f 66 20 74 68 65 20 5b 70 61 72 61 6d s] of the [param
1bdd0 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e eter]. .** </li>
1bde0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ol>.**.**
1bdf0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
1be00 20 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 [H13011] [H1301
1be10 32 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 2] [H13013] [H13
1be20 30 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 014] [H13015] [H
1be30 31 33 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 13016] [H13019]
1be40 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 53 [H13021].**.*/.S
1be50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1be60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 lite3_prepare(.
1be70 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1be80 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
1be90 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
1bea0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
1beb0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
1bec0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
1bed0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
1bee0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
1bef0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
1bf00 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
1bf10 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
1bf20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
1bf30 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
1bf40 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
1bf50 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1bf60 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
1bf70 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
1bf80 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
1bf90 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c f zSql */.);.SQL
1bfa0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1bfb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a te3_prepare_v2(.
1bfc0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1bfd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
1bfe0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
1bff0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
1c000 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
1c010 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
1c020 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
1c030 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
1c040 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
1c050 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
1c060 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
1c070 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
1c080 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
1c090 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
1c0a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1c0b0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
1c0c0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
1c0d0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
1c0e0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 of zSql */.);.SQ
1c0f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1c100 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a ite3_prepare16(.
1c110 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1c120 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
1c130 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
1c140 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
1c150 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
1c160 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
1c170 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
1c180 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
1c190 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
1c1a0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
1c1b0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
1c1c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
1c1d0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
1c1e0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
1c1f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
1c200 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
1c210 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
1c220 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
1c230 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 of zSql */.);.S
1c240 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1c250 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
1c260 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
1c270 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
1c280 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
1c290 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
1c2a0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
1c2b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
1c2c0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a UTF-16 encoded *
1c2d0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
1c2e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
1c2f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
1c300 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
1c310 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
1c320 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
1c330 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
1c340 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
1c350 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 void **pzTail
1c360 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
1c370 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
1c380 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
1c390 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1c3a0 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 EF: Retrieving S
1c3b0 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 tatement SQL {H1
1c3c0 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 3100} <H13000>.*
1c3d0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
1c3e0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
1c3f0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 to retrieve a sa
1c400 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ved copy of the
1c410 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 original.** SQL
1c420 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 text used to cre
1c430 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 ate a [prepared
1c440 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 statement] if th
1c450 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 at statement was
1c460 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 .** compiled usi
1c470 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
1c480 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1c490 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
1c4a0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
1c4b0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1c4c0 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b 48 :.** [H13101] [H
1c4d0 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d 0a 13102] [H13103].
1c4e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
1c4f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
1c500 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 3_sql(sqlite3_st
1c510 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
1c520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e ** CAPI3REF: Dyn
1c530 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 amically Typed V
1c540 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 alue Object {H15
1c550 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 000} <S20200>.**
1c560 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 KEYWORDS: {prot
1c570 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
1c580 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 lue} {unprotecte
1c590 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d d sqlite3_value}
1c5a0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 .**.** SQLite us
1c5b0 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 es the sqlite3_v
1c5c0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 alue object to r
1c5d0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c epresent all val
1c5e0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 ues.** that can
1c5f0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 be stored in a d
1c600 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 atabase table. S
1c610 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
1c620 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 ic typing.** for
1c630 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 the values it s
1c640 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73 74 tores. Values st
1c650 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f ored in sqlite3_
1c660 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a value objects.**
1c670 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 can be integers
1c680 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 , floating point
1c690 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 values, strings
1c6a0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c , BLOBs, or NULL
1c6b0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 ..**.** An sqlit
1c6c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
1c6d0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 may be either "p
1c6e0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e rotected" or "un
1c6f0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 protected"..** S
1c700 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 ome interfaces r
1c710 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 equire a protect
1c720 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1c730 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 . Other interfa
1c740 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 ces.** will acce
1c750 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 pt either a prot
1c760 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 ected or an unpr
1c770 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
1c780 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 value..** Every
1c790 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
1c7a0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 ccepts sqlite3_v
1c7b0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 alue arguments s
1c7c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 pecifies.** whet
1c7d0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 her or not it re
1c7e0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 quires a protect
1c7f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1c800 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d ..**.** The term
1c810 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e s "protected" an
1c820 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 d "unprotected"
1c830 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 refer to whether
1c840 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 or not.** a mut
1c850 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 ex is held. A i
1c860 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 nternal mutex is
1c870 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 held for a prot
1c880 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
1c890 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 _value object bu
1c8a0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 t no mutex is he
1c8b0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ld for an unprot
1c8c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
1c8d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 _value object.
1c8e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
1c8f0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 piled to be sing
1c900 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 le-threaded.** (
1c910 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 with [SQLITE_THR
1c920 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 EADSAFE=0] and w
1c930 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 ith [sqlite3_thr
1c940 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 eadsafe()] retur
1c950 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 ning 0).** or if
1c960 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 SQLite is run i
1c970 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 n one of reduced
1c980 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a mutex modes .**
1c990 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
1c9a0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 SINGLETHREAD] or
1c9b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
1c9c0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 MULTITHREAD].**
1c9d0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f then there is no
1c9e0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
1c9f0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
1ca00 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
1ca10 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1ca20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 objects and they
1ca30 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 can be used int
1ca40 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 erchangeably. H
1ca50 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d owever,.** for m
1ca60 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 aximum code port
1ca70 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 ability it is re
1ca80 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
1ca90 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
1caa0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 till make the di
1cab0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
1cac0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 n between protec
1cad0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 ted and unprotec
1cae0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
1caf0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 alue objects eve
1cb00 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 n when not stric
1cb10 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a tly required..**
1cb20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1cb30 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 value objects th
1cb40 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 at are passed as
1cb50 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f parameters into
1cb60 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
1cb70 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 tation of [appli
1cb80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
1cb90 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 QL functions] ar
1cba0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 e protected..**
1cbb0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
1cbc0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
1cbd0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
1cbe0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
1cbf0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e is unprotected.
1cc00 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 .** Unprotected
1cc10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1cc20 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 jects may only b
1cc30 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b e used with.** [
1cc40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
1cc50 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
1cc60 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
1cc70 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 )]..** The [sqli
1cc80 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c te3_value_blob |
1cc90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
1cca0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 ype()] family of
1ccb0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 .** interfaces r
1ccc0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 equire protected
1ccd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1cce0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 bjects..*/.typed
1ccf0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 ef struct Mem sq
1cd00 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
1cd10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
1cd20 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 L Function Conte
1cd30 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 xt Object {H1600
1cd40 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 1} <S20200>.**.*
1cd50 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e * The context in
1cd60 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 which an SQL fu
1cd70 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 nction executes
1cd80 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a is stored in an.
1cd90 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ** sqlite3_conte
1cda0 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f xt object. A po
1cdb0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 inter to an sqli
1cdc0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
1cdd0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ct.** is always
1cde0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
1cdf0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d to [application-
1ce00 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
1ce10 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 tions]..** The a
1ce20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
1ce30 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
1ce40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
1ce50 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a ill pass this.**
1ce60 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 pointer through
1ce70 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b into calls to [
1ce80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
1ce90 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 nt | sqlite3_res
1cea0 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ult()],.** [sqli
1ceb0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
1cec0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 ntext()], [sqlit
1ced0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c e3_user_data()],
1cee0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
1cef0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 text_db_handle()
1cf00 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ], [sqlite3_get_
1cf10 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 auxdata()],.** a
1cf20 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 nd/or [sqlite3_s
1cf30 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a et_auxdata()]..*
1cf40 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
1cf50 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
1cf60 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
1cf70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1cf80 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 F: Binding Value
1cf90 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 s To Prepared St
1cfa0 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 atements {H13500
1cfb0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 } <S70300>.** KE
1cfc0 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 YWORDS: {host pa
1cfd0 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 rameter} {host p
1cfe0 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 arameters} {host
1cff0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d parameter name}
1d000 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
1d010 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 QL parameter} {S
1d020 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b QL parameters} {
1d030 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e parameter bindin
1d040 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 g}.**.** In the
1d050 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 SQL strings inpu
1d060 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 t to [sqlite3_pr
1d070 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
1d080 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a its variants,.**
1d090 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 literals may be
1d0a0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b replaced by a [
1d0b0 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 parameter] that
1d0c0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 matches one of f
1d0d0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 ollowing.** temp
1d0e0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c lates:.**.** <ul
1d0f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 >.** <li> ?.**
1d100 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c <li> ?NNN.** <l
1d110 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e i> :VVV.** <li>
1d120 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 @VVV.** <li>
1d130 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a $VVV.** </ul>.**
1d140 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c .** In the templ
1d150 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 ates above, NNN
1d160 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e represents an in
1d170 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a teger literal,.*
1d180 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 * and VVV repres
1d190 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d ents an alphanum
1d1a0 65 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e 20 eric identifer.
1d1b0 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 The values of t
1d1c0 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hese.** paramete
1d1d0 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 rs (also called
1d1e0 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 "host parameter
1d1f0 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 names" or "SQL p
1d200 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 arameters").** c
1d210 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 an be set using
1d220 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
1d230 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 _*() routines de
1d240 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a fined here..**.*
1d250 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
1d260 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 ment to the sqli
1d270 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
1d280 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a tines is always.
1d290 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
1d2a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
1d2b0 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e t] object return
1d2c0 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 ed from.** [sqli
1d2d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1d2e0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
1d2f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 s..**.** The sec
1d300 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
1d310 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
1d320 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 SQL parameter t
1d330 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 o be set..** The
1d340 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 leftmost SQL pa
1d350 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 rameter has an i
1d360 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e ndex of 1. When
1d370 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a the same named.
1d380 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ** SQL parameter
1d390 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 is used more th
1d3a0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 an once, second
1d3b0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a and subsequent.*
1d3c0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 * occurrences ha
1d3d0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 ve the same inde
1d3e0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f x as the first o
1d3f0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 ccurrence..** Th
1d400 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 e index for name
1d410 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e d parameters can
1d420 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 be looked up us
1d430 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
1d440 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1d450 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 er_index()] API
1d460 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 if desired. The
1d470 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f index.** for "?
1d480 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 NNN" parameters
1d490 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
1d4a0 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 NNN..** The NNN
1d4b0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 value must be be
1d4c0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 tween 1 and the
1d4d0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
1d4e0 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b ].** parameter [
1d4f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
1d500 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 IABLE_NUMBER] (d
1d510 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 efault value: 99
1d520 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 9)..**.** The th
1d530 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
1d540 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e the value to bin
1d550 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 d to the paramet
1d560 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f er..**.** In tho
1d570 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 se routines that
1d580 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 have a fourth a
1d590 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c rgument, its val
1d5a0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d ue is the.** num
1d5b0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
1d5c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 the parameter.
1d5d0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 To be clear: the
1d5e0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a value is the.**
1d5f0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 number of <u>by
1d600 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 tes</u> in the v
1d610 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 alue, not the nu
1d620 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
1d630 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f rs..** If the fo
1d640 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
1d650 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 s negative, the
1d660 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 length of the st
1d670 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e ring is.** the n
1d680 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 umber of bytes u
1d690 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a p to the first z
1d6a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a ero terminator..
1d6b0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 **.** The fifth
1d6c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
1d6d0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c te3_bind_blob(),
1d6e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
1d6f0 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c xt(), and.** sql
1d700 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
1d710 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 () is a destruct
1d720 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f or used to dispo
1d730 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f se of the BLOB o
1d740 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 r.** string afte
1d750 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e r SQLite has fin
1d760 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 ished with it. I
1d770 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 f the fifth argu
1d780 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 ment is.** the s
1d790 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 pecial value [SQ
1d7a0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 LITE_STATIC], th
1d7b0 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 en SQLite assume
1d7c0 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e s that the.** in
1d7d0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 formation is in
1d7e0 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 static, unmanage
1d7f0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 d space and does
1d800 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
1d810 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 freed..** If the
1d820 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 fifth argument
1d830 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 has the value [S
1d840 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d QLITE_TRANSIENT]
1d850 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 , then.** SQLite
1d860 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 makes its own p
1d870 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 rivate copy of t
1d880 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 he data immediat
1d890 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 ely, before.** t
1d8a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1d8b0 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 *() routine retu
1d8c0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 rns..**.** The s
1d8d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
1d8e0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 blob() routine b
1d8f0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c inds a BLOB of l
1d900 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 ength N that.**
1d910 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a is filled with z
1d920 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c eroes. A zerobl
1d930 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 ob uses a fixed
1d940 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 amount of memory
1d950 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 .** (just an int
1d960 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 eger to hold its
1d970 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 size) while it
1d980 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 is being process
1d990 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 ed..** Zeroblobs
1d9a0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f are intended to
1d9b0 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 serve as placeh
1d9c0 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 olders for BLOBs
1d9d0 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e whose.** conten
1d9e0 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 t is later writt
1d9f0 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c en using.** [sql
1da00 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c ite3_blob_open |
1da10 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f incremental BLO
1da20 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e B I/O] routines.
1da30 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 .** A negative v
1da40 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 alue for the zer
1da50 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e oblob results in
1da60 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
1da70 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 LOB..**.** The s
1da80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
1da90 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
1daa0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a called after.**
1dab0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1dac0 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 e_v2()] (and its
1dad0 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 variants) or [s
1dae0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1daf0 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 and.** before [s
1db00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
1db10 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 ** Bindings are
1db20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 not cleared by t
1db30 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
1db40 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a t()] routine..**
1db50 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 Unbound paramet
1db60 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 ers are interpre
1db70 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a ted as NULL..**.
1db80 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1db90 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 s return [SQLITE
1dba0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 _OK] on success
1dbb0 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 or an error code
1dbc0 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 if.** anything
1dbd0 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 goes wrong. [SQ
1dbe0 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 LITE_RANGE] is r
1dbf0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 eturned if the p
1dc00 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 arameter.** inde
1dc10 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 x is out of rang
1dc20 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 e. [SQLITE_NOME
1dc30 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 M] is returned i
1dc40 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 f malloc() fails
1dc50 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 ..** [SQLITE_MIS
1dc60 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 USE] might be re
1dc70 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 turned if these
1dc80 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
1dc90 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 led on a.** virt
1dca0 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 ual machine that
1dcb0 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 is the wrong st
1dcc0 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 ate or which has
1dcd0 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 already been fi
1dce0 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 nalized..** Dete
1dcf0 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 ction of misuse
1dd00 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 is unreliable.
1dd10 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
1dd20 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a uld not depend.*
1dd30 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 * on SQLITE_MISU
1dd40 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c SE returns. SQL
1dd50 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e ITE_MISUSE is in
1dd60 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 tended to indica
1dd70 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 te a.** a logic
1dd80 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 error in the app
1dd90 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 lication. Futur
1dda0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
1ddb0 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 Lite might.** pa
1ddc0 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 nic rather than
1ddd0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 return SQLITE_MI
1dde0 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 SUSE..**.** See
1ddf0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
1de00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
1de10 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 unt()],.** [sqli
1de20 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1de30 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 er_name()], and
1de40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1de50 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
1de60 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1de70 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30 36 ents:.** [H13506
1de80 5d 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 33 35 ] [H13509] [H135
1de90 31 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48 31 12] [H13515] [H1
1dea0 33 35 31 38 5d 20 5b 48 31 33 35 32 31 5d 20 5b 3518] [H13521] [
1deb0 48 31 33 35 32 34 5d 20 5b 48 31 33 35 32 37 5d H13524] [H13527]
1dec0 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48 31 .** [H13530] [H1
1ded0 33 35 33 33 5d 20 5b 48 31 33 35 33 36 5d 20 5b 3533] [H13536] [
1dee0 48 31 33 35 33 39 5d 20 5b 48 31 33 35 34 32 5d H13539] [H13542]
1def0 20 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 35 34 [H13545] [H1354
1df00 38 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a 2a 8] [H13551].**.*
1df10 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1df20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
1df30 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
1df40 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
1df50 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 d*, int n, void(
1df60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
1df70 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1df80 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 e3_bind_double(s
1df90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1dfa0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 t, double);.SQLI
1dfb0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1dfc0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 e3_bind_int(sqli
1dfd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
1dfe0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
1dff0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
1e000 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f d_int64(sqlite3_
1e010 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 stmt*, int, sqli
1e020 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 te3_int64);.SQLI
1e030 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1e040 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c e3_bind_null(sql
1e050 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
1e060 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
1e070 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
1e080 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a xt(sqlite3_stmt*
1e090 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 , int, const cha
1e0a0 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 r*, int n, void(
1e0b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
1e0c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1e0d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 e3_bind_text16(s
1e0e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1e0f0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
1e100 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 int, void(*)(voi
1e110 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 d*));.SQLITE_API
1e120 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
1e130 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f d_value(sqlite3_
1e140 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
1e150 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t sqlite3_value*
1e160 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
1e170 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a t sqlite3_bind_z
1e180 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f eroblob(sqlite3_
1e190 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 stmt*, int, int
1e1a0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 n);../*.** CAPI3
1e1b0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 REF: Number Of S
1e1c0 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 QL Parameters {H
1e1d0 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 13600} <S70300>.
1e1e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
1e1f0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ne can be used t
1e200 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 o find the numbe
1e210 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 r of [SQL parame
1e220 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 ters].** in a [p
1e230 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1e240 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 t]. SQL paramet
1e250 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f ers are tokens o
1e260 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f f the.** form "?
1e270 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 ", "?NNN", ":AAA
1e280 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 ", "$AAA", or "@
1e290 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 AAA" that serve
1e2a0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 as.** placeholde
1e2b0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 rs for values th
1e2c0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f at are [sqlite3_
1e2d0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e bind_blob | boun
1e2e0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 d].** to the par
1e2f0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 ameters at a lat
1e300 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 er time..**.** T
1e310 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 his routine actu
1e320 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 ally returns the
1e330 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 index of the la
1e340 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 rgest (rightmost
1e350 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 ).** parameter.
1e360 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 For all forms ex
1e370 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 cept ?NNN, this
1e380 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 will correspond
1e390 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 to the.** number
1e3a0 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d of unique param
1e3b0 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d eters. If param
1e3c0 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e eters of the ?NN
1e3d0 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 N are used,.** t
1e3e0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 here may be gaps
1e3f0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a in the list..**
1e400 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
1e410 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1e420 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
1e430 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
1e440 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
1e450 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 e()], and.** [sq
1e460 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
1e470 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
1e480 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
1e490 73 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a 2a s:.** [H13601].*
1e4a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1e4b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
1e4c0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 rameter_count(sq
1e4d0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
1e4e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
1e4f0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 ame Of A Host Pa
1e500 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d rameter {H13620}
1e510 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S70300>.**.**
1e520 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
1e530 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1e540 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 o the name of th
1e550 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 e n-th.** [SQL p
1e560 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b arameter] in a [
1e570 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1e580 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 nt]..** SQL para
1e590 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f meters of the fo
1e5a0 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 rm "?NNN" or ":A
1e5b0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
1e5c0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 "$AAA".** have
1e5d0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 a name which is
1e5e0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e the string "?NNN
1e5f0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
1e600 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
1e610 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e ** respectively.
1e620 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
1e630 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 ds, the initial
1e640 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 ":" or "$" or "@
1e650 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 " or "?".** is i
1e660 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 ncluded as part
1e670 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 of the name..**
1e680 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 Parameters of th
1e690 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f e form "?" witho
1e6a0 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 ut a following i
1e6b0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e nteger have no n
1e6c0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 ame.** and are a
1e6d0 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 lso referred to
1e6e0 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 as "anonymous pa
1e6f0 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a rameters"..**.**
1e700 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 The first host
1e710 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e parameter has an
1e720 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 index of 1, not
1e730 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 0..**.** If the
1e740 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 value n is out
1e750 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 of range or if t
1e760 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 he n-th paramete
1e770 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 r is.** nameless
1e780 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 , then NULL is r
1e790 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 eturned. The re
1e7a0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
1e7b0 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 .** always in UT
1e7c0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 F-8 encoding eve
1e7d0 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 n if the named p
1e7e0 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 arameter was.**
1e7f0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 originally speci
1e800 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 fied as UTF-16 i
1e810 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
1e820 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 re16()] or.** [s
1e830 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1e840 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
1e850 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
1e860 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
1e870 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
1e880 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1e890 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
1e8a0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
1e8b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1e8c0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 index()]..**.**
1e8d0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
1e8e0 20 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a 53 51 4c [H13621].*/.SQL
1e8f0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
1e900 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 ar *sqlite3_bind
1e910 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
1e920 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1e930 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
1e940 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 3REF: Index Of A
1e950 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 Parameter With
1e960 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 A Given Name {H1
1e970 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 3640} <S70300>.*
1e980 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 *.** Return the
1e990 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 index of an SQL
1e9a0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 parameter given
1e9b0 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a its name. The.*
1e9c0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 * index value re
1e9d0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 turned is suitab
1e9e0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 le for use as th
1e9f0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 e second.** para
1ea00 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
1ea10 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
1ea20 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 te3_bind()]. A
1ea30 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 zero.** is retur
1ea40 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 ned if no matchi
1ea50 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 ng parameter is
1ea60 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 found. The para
1ea70 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 meter.** name mu
1ea80 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 st be given in U
1ea90 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 TF-8 even if the
1eaa0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
1eab0 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 ent.** was prepa
1eac0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 red from UTF-16
1ead0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 text using [sqli
1eae0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
1eaf0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
1eb00 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
1eb10 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
1eb20 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
1eb30 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1eb40 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
1eb50 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
1eb60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
1eb70 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ex()]..**.** Req
1eb80 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
1eb90 31 33 36 34 31 5d 0a 2a 2f 0a 53 51 4c 49 54 45 13641].*/.SQLITE
1eba0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1ebb0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1ebc0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 index(sqlite3_st
1ebd0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 mt*, const char
1ebe0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *zName);../*.**
1ebf0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
1ec00 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 All Bindings On
1ec10 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
1ec20 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 ment {H13660} <S
1ec30 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 70300>.**.** Con
1ec40 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 trary to the int
1ec50 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 uition of many,
1ec60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
1ec70 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 ] does not reset
1ec80 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
1ec90 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e _bind_blob | bin
1eca0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 dings] on a [pre
1ecb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1ecc0 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f ..** Use this ro
1ecd0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 utine to reset a
1ece0 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 ll host paramete
1ecf0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a rs to NULL..**.*
1ed00 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
1ed10 2a 2a 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 53 ** [H13661].*/.S
1ed20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1ed30 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 lite3_clear_bind
1ed40 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ings(sqlite3_stm
1ed50 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
1ed60 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
1ed70 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 Columns In A Res
1ed80 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30 7d ult Set {H13710}
1ed90 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S10700>.**.**
1eda0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 Return the numbe
1edb0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
1edc0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 the result set r
1edd0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a eturned by the.*
1ede0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
1edf0 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 ement]. This rou
1ee00 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 tine returns 0 i
1ee10 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 f pStmt is an SQ
1ee20 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 L.** statement t
1ee30 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 hat does not ret
1ee40 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 urn data (for ex
1ee50 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 ample an [UPDATE
1ee60 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ])..**.** Requir
1ee70 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 ements:.** [H137
1ee80 31 31 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 11].*/.SQLITE_AP
1ee90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f I int sqlite3_co
1eea0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 lumn_count(sqlit
1eeb0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
1eec0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1eed0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 : Column Names I
1eee0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b n A Result Set {
1eef0 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e H13720} <S10700>
1ef00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1ef10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
1ef20 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 name assigned t
1ef30 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 o a particular c
1ef40 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 olumn.** in the
1ef50 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
1ef60 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
1ef70 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 nt. The sqlite3
1ef80 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a _column_name().*
1ef90 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 * interface retu
1efa0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1efb0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
1efc0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a ed UTF-8 string.
1efd0 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 ** and sqlite3_c
1efe0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 olumn_name16() r
1eff0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1f000 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 to a zero-termi
1f010 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 nated.** UTF-16
1f020 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 string. The fir
1f030 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
1f040 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
1f050 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 atement].** that
1f060 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
1f070 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
1f080 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 nt. The second p
1f090 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
1f0a0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 ** column number
1f0b0 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 . The leftmost
1f0c0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 column is number
1f0d0 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 0..**.** The re
1f0e0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f turned string po
1f0f0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 inter is valid u
1f100 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 ntil either the
1f110 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1f120 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 ent].** is destr
1f130 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 oyed by [sqlite3
1f140 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
1f150 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 until the next c
1f160 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 all to.** sqlite
1f170 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 3_column_name()
1f180 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
1f190 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 n_name16() on th
1f1a0 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a e same column..*
1f1b0 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f *.** If sqlite3_
1f1c0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 malloc() fails d
1f1d0 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 uring the proces
1f1e0 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 sing of either r
1f1f0 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 outine.** (for e
1f200 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 xample during a
1f210 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 conversion from
1f220 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 UTF-8 to UTF-16)
1f230 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 then a.** NULL
1f240 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
1f250 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e ned..**.** The n
1f260 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 ame of a result
1f270 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 column is the va
1f280 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 lue of the "AS"
1f290 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 clause for.** th
1f2a0 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 at column, if th
1f2b0 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 ere is an AS cla
1f2c0 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 use. If there i
1f2d0 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a s no AS clause.*
1f2e0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 * then the name
1f2f0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 of the column is
1f300 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 unspecified and
1f310 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d may change from
1f320 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 .** one release
1f330 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 of SQLite to the
1f340 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 next..**.** Req
1f350 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
1f360 31 33 37 32 31 5d 20 5b 48 31 33 37 32 33 5d 20 13721] [H13723]
1f370 5b 48 31 33 37 32 34 5d 20 5b 48 31 33 37 32 35 [H13724] [H13725
1f380 5d 20 5b 48 31 33 37 32 36 5d 20 5b 48 31 33 37 ] [H13726] [H137
1f390 32 37 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 27].*/.SQLITE_AP
1f3a0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
1f3b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
1f3c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
1f3d0 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f int N);.SQLITE_
1f3e0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
1f3f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
1f400 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
1f410 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a mt*, int N);../*
1f420 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f .** CAPI3REF: So
1f430 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 urce Of Data In
1f440 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b A Query Result {
1f450 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e H13740} <S10700>
1f460 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1f470 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 tines provide a
1f480 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 means to determi
1f490 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f ne what column o
1f4a0 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 f what.** table
1f4b0 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73 in which databas
1f4c0 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 e a result of a
1f4d0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
1f4e0 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a nt comes from..*
1f4f0 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 * The name of th
1f500 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 e database or ta
1f510 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 ble or column ca
1f520 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 n be returned as
1f530 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 .** either a UTF
1f540 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 -8 or UTF-16 str
1f550 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 ing. The _datab
1f560 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 ase_ routines re
1f570 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 turn.** the data
1f580 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f base name, the _
1f590 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 table_ routines
1f5a0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 return the table
1f5b0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 name, and.** th
1f5c0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e e origin_ routin
1f5d0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f es return the co
1f5e0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 lumn name..** Th
1f5f0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
1f600 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c g is valid until
1f610 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
1f620 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 tatement] is des
1f630 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 troyed.** using
1f640 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
1f650 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 e()] or until th
1f660 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 e same informati
1f670 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a on is requested.
1f680 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 ** again in a di
1f690 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 fferent encoding
1f6a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 ..**.** The name
1f6b0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 s returned are t
1f6c0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 he original un-a
1f6d0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 liased names of
1f6e0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c the.** database,
1f6f0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 table, and colu
1f700 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 mn..**.** The fi
1f710 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
1f720 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 the following ca
1f730 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 lls is a [prepar
1f740 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
1f750 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
1f760 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 s return informa
1f770 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e tion about the N
1f780 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e th column return
1f790 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 ed by.** the sta
1f7a0 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 tement, where N
1f7b0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 is the second fu
1f7c0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
1f7d0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 .**.** If the Nt
1f7e0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
1f7f0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 d by the stateme
1f800 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 nt is an express
1f810 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 ion or.** subque
1f820 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 ry and is not a
1f830 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 column value, th
1f840 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 en all of these
1f850 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
1f860 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 .** NULL. These
1f870 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 routine might a
1f880 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 lso return NULL
1f890 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f if a memory allo
1f8a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 cation error.**
1f8b0 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 occurs. Otherwi
1f8c0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 se, they return
1f8d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
1f8e0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
1f8f0 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 e, table.** and
1f900 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 column that quer
1f910 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 y result column
1f920 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 was extracted fr
1f930 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 om..**.** As wit
1f940 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 h all other SQLi
1f950 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 te APIs, those p
1f960 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 ostfixed with "1
1f970 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 6" return.** UTF
1f980 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 -16 encoded stri
1f990 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 ngs, the other f
1f9a0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
1f9b0 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a UTF-8. {END}.**.
1f9c0 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 ** These APIs ar
1f9d0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 e only available
1f9e0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 if the library
1f9f0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 was compiled wit
1fa00 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
1fa10 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d _ENABLE_COLUMN_M
1fa20 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 ETADATA] C-prepr
1fa30 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 ocessor symbol d
1fa40 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 efined..**.** {A
1fa50 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 13751}.** If two
1fa60 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
1fa70 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
1fa80 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
1fa90 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 nes against the
1faa0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 same.** prepared
1fab0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 statement and c
1fac0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d olumn at the sam
1fad0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
1fae0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 results are.** u
1faf0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
1fb00 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
1fb10 20 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 37 34 [H13741] [H1374
1fb20 32 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 31 33 2] [H13743] [H13
1fb30 37 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b 48 744] [H13745] [H
1fb40 31 33 37 34 36 5d 20 5b 48 31 33 37 34 38 5d 0a 13746] [H13748].
1fb50 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 **.** If two or
1fb60 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c more threads cal
1fb70 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a l one or more.**
1fb80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
1fb90 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c _database_name |
1fba0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 column metadata
1fbb0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 interfaces].**
1fbc0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 for the same [pr
1fbd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1fbe0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c ] and result col
1fbf0 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 umn.** at the sa
1fc00 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 me time then the
1fc10 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
1fc20 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 efined..*/.SQLIT
1fc30 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
1fc40 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
1fc50 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 _database_name(s
1fc60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
1fc70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
1fc80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
1fc90 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
1fca0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
1fcb0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
1fcc0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
1fcd0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
1fce0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 mn_table_name(sq
1fcf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
1fd00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
1fd10 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
1fd20 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
1fd30 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
1fd40 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
1fd50 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
1fd60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
1fd70 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 rigin_name(sqlit
1fd80 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 e3_stmt*,int);.S
1fd90 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
1fda0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
1fdb0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
1fdc0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
1fdd0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ,int);../*.** CA
1fde0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 PI3REF: Declared
1fdf0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 Datatype Of A Q
1fe00 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 uery Result {H13
1fe10 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 760} <S10700>.**
1fe20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
1fe30 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 rameter is a [pr
1fe40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1fe50 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 ]..** If this st
1fe60 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 atement is a [SE
1fe70 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
1fe80 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 and the Nth colu
1fe90 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 mn of the.** ret
1fea0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 urned result set
1feb0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 of that [SELECT
1fec0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c ] is a table col
1fed0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 umn (not an.** e
1fee0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
1fef0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 query) then the
1ff00 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 declared type of
1ff10 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f the table.** co
1ff20 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 lumn is returned
1ff30 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f . If the Nth co
1ff40 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
1ff50 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 lt set is an.**
1ff60 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
1ff70 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e bquery, then a N
1ff80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
1ff90 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 eturned..** The
1ffa0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
1ffb0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 is always UTF-8
1ffc0 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a encoded. {END}.*
1ffd0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
1ffe0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 , given the data
1fff0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a base schema:.**.
20000 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 ** CREATE TABLE
20010 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a t1(c1 VARIANT);.
20020 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f **.** and the fo
20030 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e llowing statemen
20040 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
20050 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 :.**.** SELECT c
20060 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 1 + 1, c1 FROM t
20070 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 1;.**.** this ro
20080 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 utine would retu
20090 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 rn the string "V
200a0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 ARIANT" for the
200b0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a second result.**
200c0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 column (i==1),
200d0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 and a NULL point
200e0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 er for the first
200f0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 result column (
20100 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c i==0)..**.** SQL
20110 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
20120 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
20130 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 . So just becau
20140 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 se a column.** i
20150 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f s declared to co
20160 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c ntain a particul
20170 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 ar type does not
20180 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a mean that the.*
20190 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e * data stored in
201a0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 that column is
201b0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 of the declared
201c0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 type. SQLite is
201d0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 .** strongly typ
201e0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 ed, but the typi
201f0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f ng is dynamic no
20200 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a t static. Type.
20210 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
20220 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
20230 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
20240 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
20250 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
20260 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
20270 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
20280 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b s:.** [H13761] [
20290 48 31 33 37 36 32 5d 20 5b 48 31 33 37 36 33 5d H13762] [H13763]
202a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
202b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
202c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
202d0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a pe(sqlite3_stmt*
202e0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
202f0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
20300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
20310 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f ltype16(sqlite3_
20320 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
20330 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 ** CAPI3REF: Eva
20340 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 luate An SQL Sta
20350 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 tement {H13200}
20360 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 <S10000>.**.** A
20370 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 fter a [prepared
20380 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 statement] has
20390 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 been prepared us
203a0 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 ing either.** [s
203b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
203c0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
203d0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
203e0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c or one of the l
203f0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
20400 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ces [sqlite3_pre
20410 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 pare()] or [sqli
20420 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
20430 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a , this function.
20440 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ** must be calle
20450 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 d one or more ti
20460 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 mes to evaluate
20470 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a the statement..*
20480 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 *.** The details
20490 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 of the behavior
204a0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
204b0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 step() interface
204c0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 depend.** on wh
204d0 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d ether the statem
204e0 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 ent was prepared
204f0 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 using the newer
20500 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a "v2" interface.
20510 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
20520 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
20530 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
20540 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c _v2()] or the ol
20550 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e der legacy.** in
20560 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 terface [sqlite3
20570 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
20580 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
20590 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 16()]. The use
205a0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 of the.** new "v
205b0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 2" interface is
205c0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
205d0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 new applications
205e0 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a but the legacy.
205f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c ** interface wil
20600 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 l continue to be
20610 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a supported..**.*
20620 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 * In the legacy
20630 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
20640 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
20650 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
20660 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 TE_BUSY],.** [SQ
20670 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
20680 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
20690 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
206a0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
206b0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 With the "v2" i
206c0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 nterface, any of
206d0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 the other [resu
206e0 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 lt codes] or.**
206f0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
20700 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 codes] might be
20710 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c returned as wel
20720 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 l..**.** [SQLITE
20730 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 _BUSY] means tha
20740 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 t the database e
20750 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 ngine was unable
20760 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a to acquire the.
20770 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b ** database lock
20780 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f s it needs to do
20790 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 its job. If th
207a0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
207b0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 [COMMIT].** or
207c0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f occurs outside o
207d0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 f an explicit tr
207e0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
207f0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 you can retry th
20800 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 e.** statement.
20810 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
20820 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d t is not a [COMM
20830 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 IT] and occurs w
20840 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 ithin a.** expli
20850 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 cit transaction
20860 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 then you should
20870 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 rollback the tra
20880 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a nsaction before.
20890 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a ** continuing..*
208a0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e *.** [SQLITE_DON
208b0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
208c0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 e statement has
208d0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
208e0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ng.** successful
208f0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ly. sqlite3_ste
20900 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
20910 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
20920 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a n this virtual.*
20930 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 * machine withou
20940 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 t first calling
20950 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
20960 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 ] to reset the v
20970 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
20980 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e e back to its in
20990 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a itial state..**.
209a0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 ** If the SQL st
209b0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 atement being ex
209c0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 ecuted returns a
209d0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 ny data, then [S
209e0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 QLITE_ROW].** is
209f0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 returned each t
20a00 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 ime a new row of
20a10 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 data is ready f
20a20 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 or processing by
20a30 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 the.** caller.
20a40 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 The values may b
20a50 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 e accessed using
20a60 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 the [column acc
20a70 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a ess functions]..
20a80 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
20a90 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 ) is called agai
20aa0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 n to retrieve th
20ab0 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 e next row of da
20ac0 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ta..**.** [SQLIT
20ad0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 E_ERROR] means t
20ae0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 hat a run-time e
20af0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 rror (such as a
20b00 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 constraint.** vi
20b10 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 olation) has occ
20b20 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f urred. sqlite3_
20b30 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
20b40 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
20b50 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 n on.** the VM.
20b60 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e More information
20b70 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 may be found by
20b80 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
20b90 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3_errmsg()]..**
20ba0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 With the legacy
20bb0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 interface, a mor
20bc0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
20bd0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 code (for examp
20be0 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 le,.** [SQLITE_I
20bf0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 NTERRUPT], [SQLI
20c00 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c TE_SCHEMA], [SQL
20c10 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e ITE_CORRUPT], an
20c20 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 d so forth).** c
20c30 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 an be obtained b
20c40 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
20c50 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 e3_reset()] on t
20c60 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
20c70 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 statement]. In
20c80 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
20c90 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
20ca0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
20cb0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
20cc0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
20cd0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
20ce0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
20cf0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
20d00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
20d10 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
20d20 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
20d30 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
20d40 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 ed on a [prepare
20d50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
20d60 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 t has.** already
20d70 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 been [sqlite3_f
20d80 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
20d90 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 zed] or on one t
20da0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 hat had.** previ
20db0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
20dc0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
20dd0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
20de0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
20df0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
20e00 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
20e10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
20e20 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
20e30 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
20e40 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
20e50 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
20e60 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 ..**.** <b>Goofy
20e70 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 Interface Alert
20e80 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 :</b> In the leg
20e90 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
20ea0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 he sqlite3_step(
20eb0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 ).** API always
20ec0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 returns a generi
20ed0 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 c error code, [S
20ee0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f QLITE_ERROR], fo
20ef0 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 llowing any.** e
20f00 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 rror other than
20f10 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e [SQLITE_BUSY] an
20f20 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 d [SQLITE_MISUSE
20f30 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c ]. You must cal
20f40 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 l.** [sqlite3_re
20f50 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
20f60 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
20f70 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 n order to find
20f80 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 one of the.** sp
20f90 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f ecific [error co
20fa0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 des] that better
20fb0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 describes the e
20fc0 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 rror..** We admi
20fd0 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 t that this is a
20fe0 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 goofy design.
20ff0 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 The problem has
21000 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 been fixed.** wi
21010 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 th the "v2" inte
21020 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 rface. If you p
21030 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f repare all of yo
21040 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ur SQL statement
21050 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 s.** using eithe
21060 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
21070 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
21080 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
21090 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 2()] instead.**
210a0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 of the legacy [s
210b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
210c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
210d0 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 repare16()] inte
210e0 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 rfaces,.** then
210f0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 the more specifi
21100 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 c [error codes]
21110 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 are returned dir
21120 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 ectly.** by sqli
21130 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 te3_step(). The
21140 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 use of the "v2"
21150 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 interface is re
21160 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a commended..**.**
21170 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
21180 2a 20 5b 48 31 33 32 30 32 5d 20 5b 48 31 35 33 * [H13202] [H153
21190 30 34 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48 31 04] [H15306] [H1
211a0 35 33 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a 2a 5308] [H15310].*
211b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
211c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 sqlite3_step(sq
211d0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
211e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
211f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
21200 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 in a result set
21210 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 {H13770} <S1070
21220 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 0>.**.** Returns
21230 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 the number of v
21240 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 alues in the cur
21250 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
21260 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a result set..**.*
21270 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
21280 2a 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 33 ** [H13771] [H13
21290 37 37 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 772].*/.SQLITE_A
212a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 PI int sqlite3_d
212b0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 ata_count(sqlite
212c0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
212d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
212e0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 Fundamental Dat
212f0 61 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d 20 atypes {H10265}
21300 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30 3e <S10110><S10120>
21310 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
21320 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
21330 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79 20 76 {H10266} Every v
21340 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 alue in SQLite h
21350 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 as one of five f
21360 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 undamental datat
21370 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ypes:.**.** <ul>
21380 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 .** <li> 64-bit
21390 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
213a0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 * <li> 64-bit IE
213b0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e EE floating poin
213c0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e t number.** <li>
213d0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 string.** <li>
213e0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c BLOB.** <li> NUL
213f0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d L.** </ul> {END}
21400 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
21410 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 stants are codes
21420 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f for each of tho
21430 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 se types..**.**
21440 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 Note that the SQ
21450 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 LITE_TEXT consta
21460 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 nt was also used
21470 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 in SQLite versi
21480 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f on 2.** for a co
21490 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 mpletely differe
214a0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 nt meaning. Sof
214b0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 tware that links
214c0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a against both.**
214d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
214e0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 2 and SQLite ver
214f0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 sion 3 should us
21500 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 e SQLITE3_TEXT,
21510 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 not.** SQLITE_TE
21520 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 XT..*/.#define S
21530 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 QLITE_INTEGER 1
21540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21550 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 FLOAT 2.#defi
21560 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 ne SQLITE_BLOB
21570 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
21580 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 ITE_NULL 5.#
21590 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 ifdef SQLITE_TEX
215a0 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 T.# undef SQLITE
215b0 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 _TEXT.#else.# de
215c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 fine SQLITE_TEXT
215d0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 3.#endif.#d
215e0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 efine SQLITE3_TE
215f0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 XT 3../*.**
21600 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
21610 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 Values From A Q
21620 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c 53 uery {H13800} <S
21630 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 10700>.** KEYWOR
21640 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 DS: {column acce
21650 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a ss functions}.**
21660 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
21670 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 es form the "res
21680 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69 ult set query" i
21690 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
216a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
216b0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
216c0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 n about a single
216d0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 column of the c
216e0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 urrent.** result
216f0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e row of a query.
21700 20 20 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 In every case
21710 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
21720 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a nt is a pointer.
21730 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 ** to the [prepa
21740 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
21750 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 hat is being eva
21760 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c luated (the [sql
21770 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 ite3_stmt*].** t
21780 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 hat was returned
21790 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 from [sqlite3_p
217a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
217b0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 one of its varia
217c0 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 nts).** and the
217d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
217e0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 is the index of
217f0 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 the column for w
21800 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e hich information
21810 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 .** should be re
21820 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 turned. The lef
21830 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 tmost column of
21840 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 the result set h
21850 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a as the index 0..
21860 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** The number of
21870 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
21880 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 result can be de
21890 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a termined using.*
218a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
218b0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a n_count()]..**.*
218c0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
218d0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
218e0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
218f0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
21900 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c or if the.** col
21910 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 umn index is out
21920 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 of range, the r
21930 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
21940 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ed..** These rou
21950 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 tines may only b
21960 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 e called when th
21970 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
21980 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
21990 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
219a0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
219b0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a OW] and neither.
219c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
219d0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 t()] nor [sqlite
219e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 3_finalize()] ha
219f0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 ve been called s
21a00 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 ubsequently..**
21a10 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 If any of these
21a20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
21a30 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
21a40 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
21a50 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
21a60 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
21a70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21a80 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a has returned.**
21a90 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
21aa0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
21ab0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 W], the results
21ac0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
21ad0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 * If [sqlite3_st
21ae0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
21af0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
21b00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
21b10 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 )].** are called
21b20 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e from a differen
21b30 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 t thread while a
21b40 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
21b50 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 ines.** are pend
21b60 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
21b70 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
21b80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ned..**.** The s
21b90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
21ba0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 pe() routine ret
21bb0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c urns the.** [SQL
21bc0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
21bd0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 tatype code] for
21be0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 the initial dat
21bf0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 a type.** of the
21c00 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 result column.
21c10 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 The returned va
21c20 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 lue is one of [S
21c30 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a QLITE_INTEGER],.
21c40 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 ** [SQLITE_FLOAT
21c50 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d ], [SQLITE_TEXT]
21c60 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c , [SQLITE_BLOB],
21c70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c or [SQLITE_NULL
21c80 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a ]. The value.**
21c90 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
21ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
21cb0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 () is only meani
21cc0 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 ngful if no type
21cd0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 .** conversions
21ce0 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 have occurred as
21cf0 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 described below
21d00 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 . After a type
21d10 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 conversion,.** t
21d20 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
21d30 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
21d40 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e umn_type() is un
21d50 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 defined. Future
21d60 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 .** versions of
21d70 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 SQLite may chang
21d80 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f e the behavior o
21d90 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e f sqlite3_column
21da0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f _type().** follo
21db0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 wing a type conv
21dc0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 ersion..**.** If
21dd0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
21de0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 BLOB or UTF-8 s
21df0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 tring then the s
21e00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
21e10 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 tes().** routine
21e20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
21e30 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
21e40 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 that BLOB or str
21e50 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 ing..** If the r
21e60 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 esult is a UTF-1
21e70 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 6 string, then s
21e80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
21e90 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a tes() converts.*
21ea0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 * the string to
21eb0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 UTF-8 and then r
21ec0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
21ed0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 r of bytes..** I
21ee0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
21ef0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 a numeric value
21f00 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
21f10 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 umn_bytes() uses
21f20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
21f30 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
21f40 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
21f50 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 o a UTF-8 string
21f60 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 and returns.**
21f70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
21f80 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 tes in that stri
21f90 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 ng..** The value
21fa0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e returned does n
21fb0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a ot include the z
21fc0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 ero terminator a
21fd0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 t the end.** of
21fe0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 the string. For
21ff0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 clarity: the va
22000 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 lue returned is
22010 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
22020 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 bytes in the st
22030 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 ring, not the nu
22040 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
22050 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 rs..**.** String
22060 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 s returned by sq
22070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
22080 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
22090 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c column_text16(),
220a0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 .** even empty s
220b0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 trings, are alwa
220c0 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 ys zero terminat
220d0 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a ed. The return.
220e0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 ** value from sq
220f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
22100 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c b() for a zero-l
22110 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e ength BLOB is an
22120 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f arbitrary.** po
22130 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 inter, possibly
22140 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e even a NULL poin
22150 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ter..**.** The s
22160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
22170 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 tes16() routine
22180 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 is similar to sq
22190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
221a0 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 es().** but leav
221b0 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e es the result in
221c0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 UTF-16 in nativ
221d0 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 e byte order ins
221e0 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a tead of UTF-8..*
221f0 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 * The zero termi
22200 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 nator is not inc
22210 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f luded in this co
22220 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f unt..**.** The o
22230 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
22240 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
22250 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e n_value()] is an
22260 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
22270 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
22280 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 object. An unpr
22290 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
222a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 value object.**
222b0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
222c0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 with [sqlite3_b
222d0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 ind_value()] and
222e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
222f0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 _value()]..** If
22300 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 the [unprotecte
22310 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
22320 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
22330 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
22340 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
22350 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f is used in any o
22360 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 ther way, includ
22370 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 ing calls.** to
22380 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
22390 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
223a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
223b0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 lue_text()],.**
223c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 or [sqlite3_valu
223d0 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e e_bytes()], then
223e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
223f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
22400 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
22410 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 attempt to conv
22420 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 ert the value wh
22430 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e ere appropriate.
22440 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 For.** example
22450 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 , if the interna
22460 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e l representation
22470 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 is FLOAT and a
22480 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 text result.** i
22490 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 s requested, [sq
224a0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
224b0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e ] is used intern
224c0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 ally to perform
224d0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f the.** conversio
224e0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e n automatically.
224f0 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 The following
22500 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 table details th
22510 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a e conversions.**
22520 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 that are applie
22530 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 d:.**.** <blockq
22540 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 uote>.** <table
22550 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c border="1">.** <
22560 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c tr><th> Internal
22570 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 <br>Type <th> Re
22580 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 quested<br>Type
22590 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e <th> Conversion
225a0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 .**.** <tr><td>
225b0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e NULL <td> IN
225c0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 TEGER <td> Res
225d0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e ult is 0.** <tr>
225e0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
225f0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
22600 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a > Result is 0.0.
22610 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
22620 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 L <td> TEXT
22630 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
22640 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a is NULL pointer.
22650 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
22660 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 L <td> BLOB
22670 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
22680 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a is NULL pointer.
22690 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
226a0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 GER <td> FLOAT
226b0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 <td> Convert
226c0 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f from integer to
226d0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
226e0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
226f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
22700 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 ASCII rendering
22710 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a of the integer.*
22720 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
22730 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 ER <td> BLOB
22740 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 <td> Same as
22750 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a INTEGER->TEXT.**
22760 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
22770 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
22780 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 <td> Convert f
22790 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 rom float to int
227a0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e eger.** <tr><td>
227b0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 FLOAT <td>
227c0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 TEXT <td> AS
227d0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 CII rendering of
227e0 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 the float.** <t
227f0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
22800 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
22810 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 td> Same as FLOA
22820 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c T->TEXT.** <tr><
22830 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
22840 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
22850 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c Use atoi().** <
22860 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
22870 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
22880 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a <td> Use atof().
22890 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 ** <tr><td> TEX
228a0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 T <td> BLOB
228b0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e <td> No chan
228c0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ge.** <tr><td>
228d0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 BLOB <td> INT
228e0 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 EGER <td> Conv
228f0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e ert to TEXT then
22900 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c use atoi().** <
22910 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
22920 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
22930 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 <td> Convert to
22940 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 TEXT then use at
22950 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e of().** <tr><td>
22960 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
22970 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 TEXT <td> Ad
22980 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 d a zero termina
22990 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a tor if needed.**
229a0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 </table>.** </b
229b0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
229c0 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 The table above
229d0 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 makes reference
229e0 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c to standard C l
229f0 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 ibrary functions
22a00 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 atoi().** and a
22a10 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 tof(). SQLite d
22a20 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 oes not really u
22a30 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f se these functio
22a40 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a ns. It has its.
22a50 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e ** own equivalen
22a60 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 t internal routi
22a70 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 nes. The atoi()
22a80 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 and atof() name
22a90 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e s are.** used in
22aa0 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 the table for b
22ab0 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 revity and becau
22ac0 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 se they are fami
22ad0 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 liar to most.**
22ae0 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a C programmers..*
22af0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 *.** Note that w
22b00 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 hen type convers
22b10 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e ions occur, poin
22b20 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 ters returned by
22b30 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 prior.** calls
22b40 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
22b50 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 n_blob(), sqlite
22b60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
22b70 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 and/or.** sqlit
22b80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
22b90 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 () may be invali
22ba0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 dated..** Type c
22bb0 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 onversions and p
22bc0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 ointer invalidat
22bd0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 ions might occur
22be0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f .** in the follo
22bf0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a wing cases:.**.*
22c00 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 * <ul>.** <li> T
22c10 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
22c20 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 nt is a BLOB and
22c30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
22c40 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 text() or.**
22c50 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
22c60 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
22c70 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 led. A zero-ter
22c80 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a minator might.**
22c90 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 need to be
22ca0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 added to the st
22cb0 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c ring.</li>.** <l
22cc0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
22cd0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 ontent is UTF-8
22ce0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 text and sqlite3
22cf0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
22d00 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
22d10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
22d20 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
22d30 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 The content mus
22d40 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a t be converted.*
22d50 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 * to UTF-16
22d60 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
22d70 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
22d80 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 nt is UTF-16 tex
22d90 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f t and sqlite3_co
22da0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a lumn_bytes() or.
22db0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
22dc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 column_text() is
22dd0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f called. The co
22de0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f ntent must be co
22df0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 nverted.**
22e00 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a to UTF-8.</li>.*
22e10 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f * </ul>.**.** Co
22e20 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 nversions betwee
22e30 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 n UTF-16be and U
22e40 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 TF-16le are alwa
22e50 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 ys done in place
22e60 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 and do.** not i
22e70 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f nvalidate a prio
22e80 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 r pointer, thoug
22e90 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 h of course the
22ea0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 content of the b
22eb0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 uffer.** that th
22ec0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 e prior pointer
22ed0 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 points to will h
22ee0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 ave been modifie
22ef0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a d. Other kinds.
22f00 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e ** of conversion
22f10 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 are done in pla
22f20 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f ce when it is po
22f30 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 ssible, but some
22f40 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 times they.** ar
22f50 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 e not possible a
22f60 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 nd in those case
22f70 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 s prior pointers
22f80 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 are invalidated
22f90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 ..**.** The safe
22fa0 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 st and easiest t
22fb0 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 o remember polic
22fc0 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 y is to invoke t
22fd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hese routines.**
22fe0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 in one of the f
22ff0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a ollowing ways:.*
23000 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c *.** <ul>.** <l
23010 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
23020 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 _text() followed
23030 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
23040 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
23050 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
23060 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
23070 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
23080 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
23090 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 </li>.** <li>sq
230a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
230b0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 t16() followed b
230c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
230d0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a _bytes16()</li>.
230e0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ul>.**.** I
230f0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 n other words, y
23100 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 ou should call s
23110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
23120 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 xt(),.** sqlite3
23130 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 _column_blob(),
23140 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
23150 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 n_text16() first
23160 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 to force the re
23170 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 sult.** into the
23180 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c desired format,
23190 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c then invoke sql
231a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
231b0 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 s() or.** sqlite
231c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
231d0 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 () to find the s
231e0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ize of the resul
231f0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 t. Do not mix c
23200 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 alls.** to sqlit
23210 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
23220 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
23230 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 mn_blob() with c
23240 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 alls to.** sqlit
23250 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
23260 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6(), and do not
23270 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c mix calls to sql
23280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
23290 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 16().** with cal
232a0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
232b0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a lumn_bytes()..**
232c0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 .** The pointers
232d0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 returned are va
232e0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 lid until a type
232f0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
23300 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 rs as.** describ
23310 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 ed above, or unt
23320 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 il [sqlite3_step
23330 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
23340 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b reset()] or.** [
23350 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
23360 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 ()] is called.
23370 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 The memory space
23380 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 used to hold st
23390 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f rings.** and BLO
233a0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f Bs is freed auto
233b0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c matically. Do <
233c0 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 b>not</b> pass t
233d0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
233e0 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 rned.** [sqlite3
233f0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c _column_blob()],
23400 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
23410 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 _text()], etc. i
23420 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nto.** [sqlite3_
23430 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 free()]..**.** I
23440 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
23450 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 ation error occu
23460 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 rs during the ev
23470 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a aluation of any.
23480 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ** of these rout
23490 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 ines, a default
234a0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 value is returne
234b0 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 d. The default
234c0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 value.** is eith
234d0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 er the integer 0
234e0 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 , the floating p
234f0 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c oint number 0.0,
23500 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f or a NULL.** po
23510 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 inter. Subseque
23520 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
23530 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
23540 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b will return.** [
23550 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a SQLITE_NOMEM]..*
23560 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
23570 73 3a 0a 2a 2a 20 5b 48 31 33 38 30 33 5d 20 5b s:.** [H13803] [
23580 48 31 33 38 30 36 5d 20 5b 48 31 33 38 30 39 5d H13806] [H13809]
23590 20 5b 48 31 33 38 31 32 5d 20 5b 48 31 33 38 31 [H13812] [H1381
235a0 35 5d 20 5b 48 31 33 38 31 38 5d 20 5b 48 31 33 5] [H13818] [H13
235b0 38 32 31 5d 20 5b 48 31 33 38 32 34 5d 0a 2a 2a 821] [H13824].**
235c0 20 5b 48 31 33 38 32 37 5d 20 5b 48 31 33 38 33 [H13827] [H1383
235d0 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 0].*/.SQLITE_API
235e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
235f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
23600 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
23610 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
23620 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
23630 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 3_column_bytes(s
23640 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
23650 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
23660 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
23670 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 column_bytes16(s
23680 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
23690 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
236a0 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 API double sqlit
236b0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 e3_column_double
236c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
236d0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
236e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
236f0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 3_column_int(sql
23700 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
23710 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
23720 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 I sqlite3_int64
23730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 sqlite3_column_i
23740 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d nt64(sqlite3_stm
23750 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
23760 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
23770 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 unsigned char *s
23780 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
23790 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a xt(sqlite3_stmt*
237a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
237b0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
237c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
237d0 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 mn_text16(sqlite
237e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
237f0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 l);.SQLITE_API i
23800 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
23810 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 n_type(sqlite3_s
23820 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
23830 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
23840 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 te3_value *sqlit
23850 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
23860 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
23870 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a nt iCol);../*.**
23880 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 CAPI3REF: Destr
23890 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 oy A Prepared St
238a0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b atement Object {
238b0 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e H13300} <S70300>
238c0 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S30100>.**.** T
238d0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
238e0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ize() function i
238f0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 s called to dele
23900 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
23910 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 tatement]..** If
23920 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
23930 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63 as executed succ
23940 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 essfully or not
23950 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c executed at all,
23960 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f then.** SQLITE_
23970 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 OK is returned.
23980 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 If execution of
23990 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 the statement fa
239a0 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 iled then an.**
239b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 [error code] or
239c0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
239d0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
239e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f d..**.** This ro
239f0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c utine can be cal
23a00 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 led at any point
23a10 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 during the exec
23a20 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 ution of the.**
23a30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
23a40 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 ent]. If the vi
23a50 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 rtual machine ha
23a60 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 s not.** complet
23a70 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 ed execution whe
23a80 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 n this routine i
23a90 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 s called, that i
23aa0 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e s like.** encoun
23ab0 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 tering an error
23ac0 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 or an [sqlite3_i
23ad0 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 nterrupt | inter
23ae0 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 rupt]..** Incomp
23af0 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 lete updates may
23b00 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
23b10 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 and transactions
23b20 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 canceled,.** de
23b30 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 pending on the c
23b40 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e ircumstances, an
23b50 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 d the.** [error
23b60 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 code] returned w
23b70 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 ill be [SQLITE_A
23b80 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 BORT]..**.** Req
23b90 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
23ba0 31 31 33 30 32 5d 20 5b 48 31 31 33 30 34 5d 0a 11302] [H11304].
23bb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
23bc0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 t sqlite3_finali
23bd0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ze(sqlite3_stmt
23be0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
23bf0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
23c00 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
23c10 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 ment Object {H13
23c20 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 330} <S70300>.**
23c30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
23c40 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
23c50 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
23c60 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
23c70 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
23c80 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
23c90 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
23ca0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
23cb0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 xecuted..** Any
23cc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 SQL statement va
23cd0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 riables that had
23ce0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f values bound to
23cf0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 them using.** t
23d00 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
23d10 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
23d20 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 bind_*() API] re
23d30 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 tain their value
23d40 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 s..** Use [sqlit
23d50 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 e3_clear_binding
23d60 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 s()] to reset th
23d70 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a e bindings..**.*
23d80 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b * {H11332} The [
23d90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
23da0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 ] interface rese
23db0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 ts the [prepared
23dc0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a statement] S.**
23dd0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 back t
23de0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
23df0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
23e00 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 **.** {H11334} I
23e10 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
23e20 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
23e30 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 e3_step(S)] for
23e40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
23e50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
23e60 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 ent] S returned
23e70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 [SQLITE_ROW] or
23e80 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a [SQLITE_DONE],.*
23e90 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 * or if
23ea0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
23eb0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 )] has never bef
23ec0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ore been called
23ed0 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 on S,.**
23ee0 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f then [sqlite3_
23ef0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e reset(S)] return
23f00 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a s [SQLITE_OK]..*
23f10 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 *.** {H11336} If
23f20 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
23f30 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
23f40 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 3_step(S)] for t
23f50 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
23f60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
23f70 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 nt] S indicated
23f80 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a an error, then.*
23f90 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
23fa0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 te3_reset(S)] re
23fb0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 turns an appropr
23fc0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 iate [error code
23fd0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 ]..**.** {H11338
23fe0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
23ff0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 eset(S)] interfa
24000 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e ce does not chan
24010 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a ge the values.**
24020 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 of any
24030 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
24040 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e lob|bindings] on
24050 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
24060 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a tatement] S..*/.
24070 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
24080 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c qlite3_reset(sql
24090 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
240a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
240b0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 EF: Create Or Re
240c0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 define SQL Funct
240d0 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 ions {H16100} <S
240e0 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 20200>.** KEYWOR
240f0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 DS: {function cr
24100 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d eation routines}
24110 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 .** KEYWORDS: {a
24120 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
24130 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d ed SQL function}
24140 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 .** KEYWORDS: {a
24150 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
24160 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
24170 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 }.**.** These tw
24180 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c o functions (col
24190 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 lectively known
241a0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 as "function cre
241b0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 ation routines")
241c0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 .** are used to
241d0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e add SQL function
241e0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 s or aggregates
241f0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 or to redefine t
24200 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f he behavior.** o
24210 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 f existing SQL f
24220 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 unctions or aggr
24230 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c egates. The onl
24240 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 y difference bet
24250 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 ween the.** two
24260 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f is that the seco
24270 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 nd parameter, th
24280 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 e name of the (s
24290 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 calar) function
242a0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c or.** aggregate,
242b0 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 is encoded in U
242c0 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 TF-8 for sqlite3
242d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
242e0 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a () and UTF-16.**
242f0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
24300 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
24310 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
24320 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
24330 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
24340 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 nection] to whic
24350 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e h the SQL.** fun
24360 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 ction is to be a
24370 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 dded. If a sing
24380 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 le program uses
24390 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 more than one da
243a0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
243b0 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c tion internally,
243c0 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 then SQL functi
243d0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 ons must be adde
243e0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 d individually t
243f0 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 o.** each databa
24400 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a se connection..*
24410 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
24420 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
24430 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c name of the SQL
24440 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
24450 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 created or.** re
24460 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 defined. The le
24470 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 ngth of the name
24480 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 is limited to 2
24490 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 55 bytes, exclus
244a0 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 ive of.** the ze
244b0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 ro-terminator.
244c0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 Note that the na
244d0 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 me length limit
244e0 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 is in bytes, not
244f0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 .** characters.
24500 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 Any attempt to
24510 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f create a functio
24520 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 n with a longer
24530 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 name.** will res
24540 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 ult in [SQLITE_E
24550 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 RROR] being retu
24560 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
24570 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
24580 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 (nArg).** is the
24590 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
245a0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 ents that the SQ
245b0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a L function or.**
245c0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 aggregate takes
245d0 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 . If this parame
245e0 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 ter is -1, then
245f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
24600 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
24610 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 may take any nu
24620 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
24630 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 s between 0 and
24640 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 the limit.** set
24650 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d by [sqlite3_lim
24660 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 it]([SQLITE_LIMI
24670 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 T_FUNCTION_ARG])
24680 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a . If the third.
24690 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 ** parameter is
246a0 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 less than -1 or
246b0 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 greater than 127
246c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
246d0 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e or is.** undefin
246e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f ed..**.** The fo
246f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 urth parameter,
24700 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 eTextRep, specif
24710 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c ies what.** [SQL
24720 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 ITE_UTF8 | text
24730 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 encoding] this S
24740 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 QL function pref
24750 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 ers for.** its p
24760 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 arameters. Any
24770 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 SQL function imp
24780 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
24790 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f ld be able to wo
247a0 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 rk.** work with
247b0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c UTF-8, UTF-16le,
247c0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 or UTF-16be. B
247d0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e ut some implemen
247e0 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a tations may be.*
247f0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 * more efficient
24800 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 with one encodi
24810 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e ng than another.
24820 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e An application
24830 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 may.** invoke s
24840 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
24850 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 nction() or sqli
24860 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
24870 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 ion16() multiple
24880 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 .** times with t
24890 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
248a0 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 but with differ
248b0 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 ent values of eT
248c0 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 extRep..** When
248d0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
248e0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
248f0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 same function ar
24900 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c e available, SQL
24910 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b ite.** will pick
24920 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e the one that in
24930 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 volves the least
24940 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 amount of data
24950 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 conversion..** I
24960 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 f there is only
24970 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 a single impleme
24980 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f ntation which do
24990 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 es not care what
249a0 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e text.** encodin
249b0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 g is used, then
249c0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
249d0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 ent should be [S
249e0 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a QLITE_ANY]..**.*
249f0 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61 * The fifth para
24a00 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 meter is an arbi
24a10 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 trary pointer.
24a20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
24a30 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e on of the.** fun
24a40 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 ction can gain a
24a50 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f ccess to this po
24a60 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c inter using [sql
24a70 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 ite3_user_data()
24a80 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 ]..**.** The sev
24a90 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 enth, eighth and
24aa0 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 ninth parameter
24ab0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 s, xFunc, xStep
24ac0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a and xFinal, are.
24ad0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 ** pointers to C
24ae0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 -language functi
24af0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ons that impleme
24b00 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
24b10 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
24b20 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 ate. A scalar SQ
24b30 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
24b40 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
24b50 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 ation of the xFu
24b60 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f nc.** callback o
24b70 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nly, NULL pointe
24b80 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 rs should be pas
24b90 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 sed as the xStep
24ba0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 and xFinal.** p
24bb0 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 arameters. An ag
24bc0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
24bd0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
24be0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
24bf0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 of xStep.** and
24c00 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 xFinal and NULL
24c10 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 should be passed
24c20 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 for xFunc. To d
24c30 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e elete an existin
24c40 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f g.** SQL functio
24c50 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 n or aggregate,
24c60 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c pass NULL for al
24c70 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e l three function
24c80 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a callbacks..**.*
24c90 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 * It is permitte
24ca0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 d to register mu
24cb0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
24cc0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
24cd0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 me.** functions
24ce0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 with the same na
24cf0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 me but with eith
24d00 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d er differing num
24d10 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d bers of.** argum
24d20 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e ents or differin
24d30 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 g preferred text
24d40 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c encodings. SQL
24d50 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
24d60 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
24d70 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f on that most clo
24d80 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 sely matches the
24d90 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 way in which th
24da0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f e.** SQL functio
24db0 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20 66 75 n is used. A fu
24dc0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
24dd0 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e ation with a non
24de0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 -negative.** nAr
24df0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 g parameter is a
24e00 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 better match th
24e10 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d an a function im
24e20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 plementation wit
24e30 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 h.** a negative
24e40 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69 6f nArg. A functio
24e50 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 n where the pref
24e60 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
24e70 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 ing.** matches t
24e80 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f he database enco
24e90 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 ding is a better
24ea0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 .** match than a
24eb0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
24ec0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 the encoding is
24ed0 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 different. .**
24ee0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 A function where
24ef0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 the encoding di
24f00 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 fference is betw
24f10 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 een UTF16le and
24f20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 UTF16be.** is a
24f30 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 closer match tha
24f40 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
24f50 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
24f60 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a difference is.**
24f70 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e between UTF8 an
24f80 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 d UTF16..**.** B
24f90 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e uilt-in function
24fa0 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 s may be overloa
24fb0 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 ded by new appli
24fc0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
24fd0 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 unctions..** The
24fe0 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 first applicati
24ff0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
25000 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e ion with a given
25010 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 name overrides
25020 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 all.** built-in
25030 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 functions in the
25040 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
25050 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 connection] with
25060 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a the same name..
25070 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 70 ** Subsequent ap
25080 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
25090 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 d functions of t
250a0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c he same name onl
250b0 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 y override .** p
250c0 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e rior application
250d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
250e0 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 ns that are an e
250f0 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 xact match for t
25100 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
25110 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 parameters and p
25120 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e referred encodin
25130 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c g..**.** An appl
25140 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
25150 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d function is perm
25160 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 itted to call ot
25170 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
25180 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 terfaces. Howev
25190 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d er, such calls m
251a0 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 ust not.** close
251b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
251c0 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e nnection nor fin
251d0 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 alize or reset t
251e0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 he prepared.** s
251f0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 tatement in whic
25200 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 h the function i
25210 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a s running..**.**
25220 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
25230 2a 20 5b 48 31 36 31 30 33 5d 20 5b 48 31 36 31 * [H16103] [H161
25240 30 36 5d 20 5b 48 31 36 31 30 39 5d 20 5b 48 31 06] [H16109] [H1
25250 36 31 31 32 5d 20 5b 48 31 36 31 31 38 5d 20 5b 6112] [H16118] [
25260 48 31 36 31 32 31 5d 20 5b 48 31 36 31 32 37 5d H16121] [H16127]
25270 0a 2a 2a 20 5b 48 31 36 31 33 30 5d 20 5b 48 31 .** [H16130] [H1
25280 36 31 33 33 5d 20 5b 48 31 36 31 33 36 5d 20 5b 6133] [H16136] [
25290 48 31 36 31 33 39 5d 20 5b 48 31 36 31 34 32 5d H16139] [H16142]
252a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
252b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
252c0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 e_function(. sq
252d0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e lite3 *db,. con
252e0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 st char *zFuncti
252f0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 onName,. int nA
25300 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 rg,. int eTextR
25310 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 ep,. void *pApp
25320 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 ,. void (*xFunc
25330 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
25340 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
25350 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
25360 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 (*xStep)(sqlite3
25370 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
25380 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
25390 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 void (*xFinal)
253a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
253b0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *).);.SQLITE_API
253c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
253d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a ate_function16(.
253e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
253f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 const void *zFu
25400 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
25410 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
25420 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
25430 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
25440 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
25450 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
25460 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
25470 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
25480 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
25490 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
254a0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
254b0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
254c0 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a text*).);../*.**
254d0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 CAPI3REF: Text
254e0 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 Encodings {H1026
254f0 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 7} <S50200> <H16
25500 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 100>.**.** These
25510 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 constant define
25520 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 integer codes t
25530 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 hat represent th
25540 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 e various.** tex
25550 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 t encodings supp
25560 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e orted by SQLite.
25570 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
25580 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 TE_UTF8
25590 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
255a0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 TE_UTF16LE
255b0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
255c0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 TE_UTF16BE
255d0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
255e0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 TE_UTF16
255f0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 4 /* Use na
25600 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
25610 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
25620 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 E_ANY
25630 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
25640 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
25650 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
25660 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c SQLITE_UTF16_AL
25670 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 IGNED 8 /* s
25680 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
25690 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a llation only */.
256a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
256b0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 Deprecated Func
256c0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 tions.** DEPRECA
256d0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TED.**.** These
256e0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 functions are [d
256f0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 eprecated]. In
25700 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 order to maintai
25710 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 n.** backwards c
25720 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
25730 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 h older code, th
25740 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f ese functions co
25750 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 ntinue .** to be
25760 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 supported. How
25770 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 ever, new applic
25780 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 ations should av
25790 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f oid.** the use o
257a0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
257b0 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f s. To help enco
257c0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 urage people to
257d0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 avoid.** using t
257e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 hese functions,
257f0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 we are not going
25800 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 to tell you wha
25810 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 t they do..*/.#i
25820 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 fndef SQLITE_OMI
25830 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c T_DEPRECATED.SQL
25840 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 ITE_API SQLITE_D
25850 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
25860 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
25870 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f count(sqlite3_co
25880 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f ntext*);.SQLITE_
25890 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
258a0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
258b0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 3_expired(sqlite
258c0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
258d0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
258e0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
258f0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 e3_transfer_bind
25900 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ings(sqlite3_stm
25910 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 t*, sqlite3_stmt
25920 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
25930 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
25940 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f int sqlite3_glo
25950 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 bal_recover(void
25960 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
25970 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
25980 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 void sqlite3_thr
25990 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 ead_cleanup(void
259a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
259b0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
259c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f int sqlite3_memo
259d0 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 ry_alarm(void(*)
259e0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 (void*,sqlite3_i
259f0 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c nt64,int),void*,
25a00 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
25a10 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
25a20 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e PI3REF: Obtainin
25a30 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 g SQL Function P
25a40 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 arameter Values
25a50 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 {H15100} <S20200
25a60 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 >.**.** The C-la
25a70 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 nguage implement
25a80 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e ation of SQL fun
25a90 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
25aa0 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 gates uses.** th
25ab0 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 is set of interf
25ac0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ace routines to
25ad0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d access the param
25ae0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a eter values on.*
25af0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f * the function o
25b00 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a r aggregate..**.
25b10 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f ** The xFunc (fo
25b20 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f r scalar functio
25b30 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f ns) or xStep (fo
25b40 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 r aggregates) pa
25b50 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b rameters.** to [
25b60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
25b70 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b unction()] and [
25b80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
25b90 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 unction16()].**
25ba0 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 define callbacks
25bb0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 that implement
25bc0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
25bd0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
25be0 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 ..** The 4th par
25bf0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 ameter to these
25c00 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 callbacks is an
25c10 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
25c20 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 s to.** [protect
25c30 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
25c40 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 ] objects. Ther
25c50 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 e is one [sqlite
25c60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
25c70 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 for.** each para
25c80 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c meter to the SQL
25c90 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 function. Thes
25ca0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 e routines are u
25cb0 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 sed to.** extrac
25cc0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 t values from th
25cd0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
25ce0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a ] objects..**.**
25cf0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
25d00 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b work only with [
25d10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
25d20 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
25d30 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 ..** Any attempt
25d40 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f to use these ro
25d50 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e utines on an [un
25d60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
25d70 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 3_value].** obje
25d80 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e ct results in un
25d90 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 defined behavior
25da0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
25db0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 utines work just
25dc0 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 like the corres
25dd0 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 ponding [column
25de0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 access functions
25df0 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 ].** except that
25e00 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 these routines
25e10 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b take a single [
25e20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
25e30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 3_value] object.
25e40 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 ** pointer inste
25e50 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 ad of a [sqlite3
25e60 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 _stmt*] pointer
25e70 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 and an integer c
25e80 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a olumn number..**
25e90 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
25ea0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 value_text16() i
25eb0 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 nterface extract
25ec0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e s a UTF-16 strin
25ed0 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 g.** in the nati
25ee0 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 ve byte-order of
25ef0 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e the host machin
25f00 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 e. The.** sqlit
25f10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 e3_value_text16b
25f20 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
25f30 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 value_text16le()
25f40 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 interfaces.** e
25f50 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 xtract UTF-16 st
25f60 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 rings as big-end
25f70 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 ian and little-e
25f80 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 ndian respective
25f90 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ly..**.** The sq
25fa0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
25fb0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 ric_type() inter
25fc0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
25fd0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 apply.** numeri
25fe0 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 c affinity to th
25ff0 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d e value. This m
26000 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 eans that an att
26010 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 empt is.** made
26020 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
26030 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 alue to an integ
26040 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 er or floating p
26050 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 oint. If.** suc
26060 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 h a conversion i
26070 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f s possible witho
26080 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 ut loss of infor
26090 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 mation (in other
260a0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 .** words, if th
260b0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 e value is a str
260c0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c ing that looks l
260d0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a ike a number).**
260e0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 then the conver
260f0 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 sion is performe
26100 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f d. Otherwise no
26110 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
26120 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 rs..** The [SQLI
26130 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
26140 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e atype] after con
26150 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 version is retur
26160 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 ned..**.** Pleas
26170 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 e pay particular
26180 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 attention to th
26190 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 e fact that the
261a0 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 pointer returned
261b0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
261c0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 3_value_blob()],
261d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
261e0 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b text()], or.** [
261f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
26200 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 xt16()] can be i
26210 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 nvalidated by a
26220 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 subsequent call
26230 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 to.** [sqlite3_v
26240 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b alue_bytes()], [
26250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
26260 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 tes16()], [sqlit
26270 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
26280 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ,.** or [sqlite3
26290 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
262a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
262b0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 utines must be c
262c0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
262d0 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a ame thread as.**
262e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
262f0 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 n that supplied
26300 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
26310 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e ue*] parameters.
26320 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
26330 6e 74 73 3a 0a 2a 2a 20 5b 48 31 35 31 30 33 5d nts:.** [H15103]
26340 20 5b 48 31 35 31 30 36 5d 20 5b 48 31 35 31 30 [H15106] [H1510
26350 39 5d 20 5b 48 31 35 31 31 32 5d 20 5b 48 31 35 9] [H15112] [H15
26360 31 31 35 5d 20 5b 48 31 35 31 31 38 5d 20 5b 48 115] [H15118] [H
26370 31 35 31 32 31 5d 20 5b 48 31 35 31 32 34 5d 0a 15121] [H15124].
26380 2a 2a 20 5b 48 31 35 31 32 37 5d 20 5b 48 31 35 ** [H15127] [H15
26390 31 33 30 5d 20 5b 48 31 35 31 33 33 5d 20 5b 48 130] [H15133] [H
263a0 31 35 31 33 36 5d 0a 2a 2f 0a 53 51 4c 49 54 45 15136].*/.SQLITE
263b0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
263c0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 *sqlite3_value_b
263d0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 lob(sqlite3_valu
263e0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
263f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
26400 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f e_bytes(sqlite3_
26410 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
26420 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
26430 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 value_bytes16(sq
26440 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
26450 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 QLITE_API double
26460 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 sqlite3_value_d
26470 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 ouble(sqlite3_va
26480 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
26490 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 I int sqlite3_va
264a0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f lue_int(sqlite3_
264b0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
264c0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
264d0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 4 sqlite3_value_
264e0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 int64(sqlite3_va
264f0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
26500 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 I const unsigned
26510 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
26520 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 alue_text(sqlite
26530 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
26540 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
26550 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
26560 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 text16(sqlite3_v
26570 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
26580 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 PI const void *s
26590 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
265a0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 t16le(sqlite3_va
265b0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
265c0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
265d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
265e0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 16be(sqlite3_val
265f0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
26600 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c int sqlite3_val
26610 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f ue_type(sqlite3_
26620 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
26630 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
26640 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 value_numeric_ty
26650 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
26660 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
26670 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 REF: Obtain Aggr
26680 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 egate Function C
26690 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 ontext {H16210}
266a0 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20200>.**.** T
266b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
266c0 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 n of aggregate S
266d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 QL functions use
266e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f this routine to
266f0 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 allocate.** a s
26700 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f tructure for sto
26710 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 ring their state
26720 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
26730 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 t time the sqlit
26740 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
26750 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 text() routine i
26760 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a s called for a.*
26770 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 * particular agg
26780 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 regate, SQLite a
26790 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 llocates nBytes
267a0 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 of memory, zeroe
267b0 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 s out that.** me
267c0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e mory, and return
267d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 s a pointer to i
267e0 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 t. On second and
267f0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
26800 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s to.** sqlite3_
26810 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
26820 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 t() for the same
26830 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
26840 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 ion index,.** th
26850 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 e same buffer is
26860 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 returned. The i
26870 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
26880 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 the aggregate c
26890 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 an use.** the re
268a0 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f turned buffer to
268b0 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 accumulate data
268c0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 ..**.** SQLite a
268d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 utomatically fre
268e0 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 es the allocated
268f0 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 buffer when the
26900 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 aggregate.** qu
26910 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a ery concludes..*
26920 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 *.** The first p
26930 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 arameter should
26940 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 be a copy of the
26950 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
26960 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 text | SQL funct
26970 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 ion context] tha
26980 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 t is the first p
26990 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
269a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 he callback rout
269b0 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ine that impleme
269c0 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 nts the aggregat
269d0 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a e function..**.*
269e0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d * This routine m
269f0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
26a00 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
26a10 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
26a20 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c he aggregate SQL
26a30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
26a40 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ning..**.** Requ
26a50 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
26a60 36 32 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 5b 6211] [H16213] [
26a70 48 31 36 32 31 35 5d 20 5b 48 31 36 32 31 37 5d H16215] [H16217]
26a80 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
26a90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 oid *sqlite3_agg
26aa0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 regate_context(s
26ab0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
26ac0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f int nBytes);../
26ad0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 *.** CAPI3REF: U
26ae0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e ser Data For Fun
26af0 63 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 ctions {H16240}
26b00 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20200>.**.** T
26b10 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f he sqlite3_user_
26b20 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
26b30 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 returns a copy
26b40 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 of.** the pointe
26b50 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 r that was the p
26b60 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 UserData paramet
26b70 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 er (the 5th para
26b80 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 meter).** of the
26b90 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
26ba0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 _function()].**
26bb0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
26bc0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
26bd0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 ] routines that
26be0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 originally.** re
26bf0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 gistered the app
26c00 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 lication defined
26c10 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d function. {END}
26c20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
26c30 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c ine must be call
26c40 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
26c50 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
26c60 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
26c70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
26c80 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
26c90 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
26ca0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 34 33 5d nts:.** [H16243]
26cb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
26cc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 oid *sqlite3_use
26cd0 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 r_data(sqlite3_c
26ce0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a ontext*);../*.**
26cf0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
26d00 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 ase Connection F
26d10 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 or Functions {H1
26d20 36 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 6250} <S60600><S
26d30 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20200>.**.** The
26d40 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
26d50 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 _db_handle() int
26d60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
26d70 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
26d80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
26d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
26da0 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 ion] (the 1st pa
26db0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 rameter).** of t
26dc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
26dd0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
26de0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
26df0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
26e00 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 ()] routines tha
26e10 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 t originally.**
26e20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 registered the a
26e30 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
26e40 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a ed function..**.
26e50 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
26e60 0a 2a 2a 20 5b 48 31 36 32 35 33 5d 0a 2a 2f 0a .** [H16253].*/.
26e70 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
26e80 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 e3 *sqlite3_cont
26e90 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 ext_db_handle(sq
26ea0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
26eb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
26ec0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c : Function Auxil
26ed0 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 iary Data {H1627
26ee0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
26ef0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
26f00 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 two functions ma
26f10 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 y be used by sca
26f20 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
26f30 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
26f40 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
26f50 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
26f60 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
26f70 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
26f80 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
26f90 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
26fa0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
26fb0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
26fc0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
26fd0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
26fe0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
26ff0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
27000 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 be preserved. T
27010 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 his may.** be us
27020 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c ed, for example,
27030 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 to add a regula
27040 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 r-expression mat
27050 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 ching scalar.**
27060 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
27070 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
27080 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
27090 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 pression is stor
270a0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 ed as.** metadat
270b0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
270c0 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 h the SQL value
270d0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 passed as the re
270e0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
270f0 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 .** pattern. Th
27100 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c e compiled regul
27110 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 ar expression ca
27120 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d n be reused on m
27130 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 ultiple.** invoc
27140 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
27150 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 me function so t
27160 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c hat the original
27170 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a pattern string.
27180 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ** does not need
27190 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 to be recompile
271a0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 d on each invoca
271b0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
271c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
271d0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
271e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
271f0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 r to the metadat
27200 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 a.** associated
27210 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
27220 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e et_auxdata() fun
27230 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e ction with the N
27240 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 th argument.** v
27250 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c alue to the appl
27260 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
27270 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 function. If no
27280 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 metadata has bee
27290 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 n ever.** been s
272a0 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 et for the Nth a
272b0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 rgument of the f
272c0 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 unction, or if t
272d0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
272e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
272f0 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 ameter has chang
27300 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 ed since the met
27310 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a a-data was set,.
27320 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ** then sqlite3_
27330 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 get_auxdata() re
27340 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
27350 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nter..**.** The
27360 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
27370 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
27380 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 saves the metada
27390 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f ta.** pointed to
273a0 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 by its 3rd para
273b0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 meter as the met
273c0 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d adata for the N-
273d0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f th.** argument o
273e0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
273f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
27400 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a on. Subsequent.
27410 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
27420 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
27430 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 ) might return t
27440 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 his data, if it
27450 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 has.** not been
27460 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 destroyed..** If
27470 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c it is not NULL,
27480 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
27490 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
274a0 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 or.** function g
274b0 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 iven by the 4th
274c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
274d0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
274e0 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 () on.** the met
274f0 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 adata when the c
27500 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e orresponding fun
27510 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 ction parameter
27520 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 changes.** or wh
27530 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
27540 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 ment completes,
27550 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 whichever comes
27560 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c first..**.** SQL
27570 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 ite is free to c
27580 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 all the destruct
27590 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 or and drop meta
275a0 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 data on any.** p
275b0 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 arameter of any
275c0 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 function at any
275d0 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 time. The only
275e0 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 guarantee is tha
275f0 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 t.** the destruc
27600 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c tor will be call
27610 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 ed before the me
27620 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 tadata is droppe
27630 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 d..**.** In prac
27640 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 tice, metadata i
27650 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 s preserved betw
27660 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c een function cal
27670 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 ls for.** expres
27680 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 sions that are c
27690 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 onstant at compi
276a0 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e le time. This in
276b0 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a cludes literal.*
276c0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c * values and SQL
276d0 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a variables..**.*
276e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
276f0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
27700 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
27710 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
27720 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
27730 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a n is running..**
27740 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
27750 3a 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 :.** [H16272] [H
27760 31 36 32 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 16274] [H16276]
27770 5b 48 31 36 32 37 37 5d 20 5b 48 31 36 32 37 38 [H16277] [H16278
27780 5d 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 53 51 ] [H16279].*/.SQ
27790 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 LITE_API void *s
277a0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
277b0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
277c0 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c xt*, int N);.SQL
277d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
277e0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
277f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
27800 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c *, int N, void*,
27810 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 void (*)(void*)
27820 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 );.../*.** CAPI3
27830 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 REF: Constants D
27840 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 efining Special
27850 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 Destructor Behav
27860 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 ior {H10280} <S3
27870 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0100>.**.** Thes
27880 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 e are special va
27890 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 lues for the des
278a0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 tructor that is
278b0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 passed in as the
278c0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 .** final argume
278d0 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c nt to routines l
278e0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ike [sqlite3_res
278f0 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 ult_blob()]. If
27900 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a the destructor.
27910 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 ** argument is S
27920 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 QLITE_STATIC, it
27930 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
27940 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 content pointer
27950 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 is constant.** a
27960 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 nd will never ch
27970 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e ange. It does n
27980 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 ot need to be de
27990 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a stroyed. The.**
279a0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
279b0 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 T value means th
279c0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 at the content w
279d0 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 ill likely chang
279e0 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 e in.** the near
279f0 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 future and that
27a00 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d SQLite should m
27a10 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 ake its own priv
27a20 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 ate copy of.** t
27a30 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 he content befor
27a40 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a e returning..**.
27a50 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 ** The typedef i
27a60 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 s necessary to w
27a70 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c ork around probl
27a80 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a ems in certain.*
27a90 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e * C++ compilers.
27aa0 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 See ticket #21
27ab0 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 91..*/.typedef v
27ac0 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 oid (*sqlite3_de
27ad0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 structor_type)(v
27ae0 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 oid*);.#define S
27af0 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 QLITE_STATIC
27b00 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 ((sqlite3_dest
27b10 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 ructor_type)0).#
27b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
27b30 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 ANSIENT ((sqli
27b40 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 te3_destructor_t
27b50 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 ype)-1)../*.** C
27b60 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 API3REF: Setting
27b70 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 The Result Of A
27b80 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b n SQL Function {
27b90 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e H16400} <S20200>
27ba0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
27bb0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 tines are used b
27bc0 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 y the xFunc or x
27bd0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 Final callbacks
27be0 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e that.** implemen
27bf0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 t SQL functions
27c00 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 and aggregates.
27c10 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 See.** [sqlite3
27c20 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
27c30 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
27c40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
27c50 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 16()].** for add
27c60 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
27c70 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ion..**.** These
27c80 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 functions work
27c90 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 very much like t
27ca0 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 he [parameter bi
27cb0 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 nding] family of
27cc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 .** functions us
27cd0 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 ed to bind value
27ce0 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 s to host parame
27cf0 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 ters in prepared
27d00 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
27d10 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 Refer to the [SQ
27d20 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 L parameter] doc
27d30 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 umentation for a
27d40 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
27d50 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
27d60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
27d70 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 blob() interface
27d80 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
27d90 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
27da0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
27db0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
27dc0 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f he BLOB whose co
27dd0 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 ntent is pointed
27de0 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 .** to by the se
27df0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 cond parameter a
27e00 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 nd which is N by
27e10 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e tes long where N
27e20 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 is the.** third
27e30 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
27e40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
27e50 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 sult_zeroblob()
27e60 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 interfaces set t
27e70 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 he result of.**
27e80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
27e90 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
27ea0 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f to be a BLOB co
27eb0 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 ntaining all zer
27ec0 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e o.** bytes and N
27ed0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 bytes in size,
27ee0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 where N is the v
27ef0 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 alue of the 2nd
27f00 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
27f10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
27f20 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 ult_double() int
27f30 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
27f40 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 result from.** a
27f50 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
27f60 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
27f70 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 o be a floating
27f80 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 point value spec
27f90 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 ified.** by its
27fa0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
27fb0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
27fc0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 result_error() a
27fd0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c nd sqlite3_resul
27fe0 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 t_error16() func
27ff0 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 tions.** cause t
28000 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 he implemented S
28010 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 QL function to t
28020 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f hrow an exceptio
28030 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 n..** SQLite use
28040 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 s the string poi
28050 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a nted to by the.*
28060 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 * 2nd parameter
28070 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c of sqlite3_resul
28080 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c t_error() or sql
28090 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
280a0 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 r16().** as the
280b0 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 text of an error
280c0 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 message. SQLit
280d0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 e interprets the
280e0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
280f0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 e string from sq
28100 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
28110 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 or() as UTF-8. S
28120 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 QLite.** interpr
28130 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 ets the string f
28140 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 rom sqlite3_resu
28150 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 lt_error16() as
28160 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 UTF-16 in native
28170 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 .** byte order.
28180 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 If the third pa
28190 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
281a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
281b0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
281c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
281d0 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 is negative the
281e0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 n SQLite takes a
281f0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
28200 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 essage all text
28210 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 up through the f
28220 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 irst zero charac
28230 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 ter..** If the t
28240 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
28250 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 o sqlite3_result
28260 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 _error() or.** s
28270 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
28280 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e ror16() is non-n
28290 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c egative then SQL
282a0 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d ite takes that m
282b0 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f any.** bytes (no
282c0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 t characters) fr
282d0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d om the 2nd param
282e0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f eter as the erro
282f0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 r message..** Th
28300 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
28310 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c _error() and sql
28320 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
28330 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 r16().** routine
28340 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 s make a private
28350 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 copy of the err
28360 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 or message text
28370 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 before.** they r
28380 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 eturn. Hence, t
28390 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
283a0 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 ion can dealloca
283b0 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 te or.** modify
283c0 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 the text after t
283d0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f hey return witho
283e0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 ut harm..** The
283f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
28400 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 rror_code() func
28410 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 tion changes the
28420 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 error code.** r
28430 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 eturned by SQLit
28440 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 e as a result of
28450 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 an error in a f
28460 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 unction. By def
28470 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 ault,.** the err
28480 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 or code is SQLIT
28490 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 E_ERROR. A subs
284a0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 equent call to s
284b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
284c0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 ror().** or sqli
284d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
284e0 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 16() resets the
284f0 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 error code to SQ
28500 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a LITE_ERROR..**.*
28510 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
28520 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e sult_toobig() in
28530 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 terface causes S
28540 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 QLite to throw a
28550 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 n error.** indic
28560 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 ating that a str
28570 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 ing or BLOB is t
28580 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 o long to repres
28590 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ent..**.** The s
285a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f qlite3_result_no
285b0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 mem() interface
285c0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f causes SQLite to
285d0 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a throw an error.
285e0 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ** indicating th
285f0 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f at a memory allo
28600 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a cation failed..*
28610 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
28620 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e _result_int() in
28630 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
28640 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a return value.**
28650 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
28660 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
28670 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 tion to be the 3
28680 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 2-bit signed int
28690 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 eger.** value gi
286a0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 ven in the 2nd a
286b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 rgument..** The
286c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
286d0 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 nt64() interface
286e0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
286f0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
28700 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
28710 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
28720 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 be the 64-bit s
28730 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
28740 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 value given in
28750 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 the 2nd argument
28760 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
28770 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 te3_result_null(
28780 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
28790 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
287a0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c e.** of the appl
287b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
287c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e function to be N
287d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ULL..**.** The s
287e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
287f0 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 xt(), sqlite3_re
28800 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a sult_text16(),.*
28810 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 * sqlite3_result
28820 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 _text16le(), and
28830 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28840 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 text16be() inter
28850 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 faces.** set the
28860 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
28870 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
28880 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
28890 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 n to be.** a tex
288a0 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 t string which i
288b0 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 s represented as
288c0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e UTF-8, UTF-16 n
288d0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
288e0 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 ,.** UTF-16 litt
288f0 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 le endian, or UT
28900 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c F-16 big endian,
28910 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
28920 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 * SQLite takes t
28930 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 he text result f
28940 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 rom the applicat
28950 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 ion from.** the
28960 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
28970 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
28980 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
28990 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 aces..** If the
289a0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
289b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
289c0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
289d0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 aces.** is negat
289e0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ive, then SQLite
289f0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 takes result te
28a00 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 xt from the 2nd
28a10 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 parameter.** thr
28a20 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
28a30 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
28a40 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 * If the 3rd par
28a50 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
28a60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
28a70 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
28a80 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
28a90 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 , then as many b
28aa0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 ytes (not charac
28ab0 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 ters) of the tex
28ac0 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 t.** pointed to
28ad0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d by the 2nd param
28ae0 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 eter are taken a
28af0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f s the applicatio
28b00 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e n-defined.** fun
28b10 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a ction result..**
28b20 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 If the 4th para
28b30 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
28b40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
28b50 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
28b60 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
28b70 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d t_blob is a non-
28b80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
28b90 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 en SQLite calls
28ba0 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e that.** function
28bb0 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 as the destruct
28bc0 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f or on the text o
28bd0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 r BLOB result wh
28be0 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e en it has.** fin
28bf0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
28c00 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 result..** If t
28c10 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
28c20 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
28c30 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
28c40 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a erfaces or to.**
28c50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28c60 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 blob is the spec
28c70 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c ial constant SQL
28c80 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e ITE_STATIC, then
28c90 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d SQLite.** assum
28ca0 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 es that the text
28cb0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 or BLOB result
28cc0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 is in constant s
28cd0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f pace and does no
28ce0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f t.** copy the co
28cf0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 ntent of the par
28d00 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 ameter nor call
28d10 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 a destructor on
28d20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 the content.** w
28d30 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 hen it has finis
28d40 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 hed using that r
28d50 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 esult..** If the
28d60 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
28d70 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
28d80 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
28d90 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 faces.** or sqli
28da0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
28db0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
28dc0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 onstant SQLITE_T
28dd0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e RANSIENT.** then
28de0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 SQLite makes a
28df0 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 copy of the resu
28e00 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 lt into space ob
28e10 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 tained from.** f
28e20 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
28e30 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 loc()] before it
28e40 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
28e50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
28e60 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 lt_value() inter
28e70 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
28e80 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 sult of.** the a
28e90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
28ea0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
28eb0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 e a copy the.**
28ec0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
28ed0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
28ee0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 ct specified by
28ef0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
28f00 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 r. The.** sqlit
28f10 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
28f20 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 ) interface make
28f30 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
28f40 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a [sqlite3_value].
28f50 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b ** so that the [
28f60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 sqlite3_value] s
28f70 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 pecified in the
28f80 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 parameter may ch
28f90 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 ange or.** be de
28fa0 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 allocated after
28fb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
28fc0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 alue() returns w
28fd0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 ithout harm..**
28fe0 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c A [protected sql
28ff0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
29000 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 ct may always be
29010 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a used where an.*
29020 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 * [unprotected s
29030 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
29040 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 ject is required
29050 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b , so either.** k
29060 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ind of [sqlite3_
29070 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 value] object ca
29080 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 n be used with t
29090 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a his interface..*
290a0 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f *.** If these ro
290b0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
290c0 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 d from within th
290d0 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 e different thre
290e0 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f ad.** than the o
290f0 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ne containing th
29100 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
29110 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
29120 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 hat received.**
29130 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
29140 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 text] pointer, t
29150 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
29160 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
29170 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
29180 20 5b 48 31 36 34 30 33 5d 20 5b 48 31 36 34 30 [H16403] [H1640
29190 36 5d 20 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 6] [H16409] [H16
291a0 34 31 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 412] [H16415] [H
291b0 31 36 34 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 16418] [H16421]
291c0 5b 48 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 [H16424].** [H16
291d0 34 32 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 427] [H16430] [H
291e0 31 36 34 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 16433] [H16436]
291f0 5b 48 31 36 34 33 39 5d 20 5b 48 31 36 34 34 32 [H16439] [H16442
29200 5d 20 5b 48 31 36 34 34 35 5d 20 5b 48 31 36 34 ] [H16445] [H164
29210 34 38 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 48].** [H16451]
29220 5b 48 31 36 34 35 34 5d 20 5b 48 31 36 34 35 37 [H16454] [H16457
29230 5d 20 5b 48 31 36 34 36 30 5d 20 5b 48 31 36 34 ] [H16460] [H164
29240 36 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 63].*/.SQLITE_AP
29250 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
29260 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 esult_blob(sqlit
29270 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
29280 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
29290 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
292a0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
292b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
292c0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f ouble(sqlite3_co
292d0 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b ntext*, double);
292e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
292f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
29300 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f error(sqlite3_co
29310 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
29320 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 ar*, int);.SQLIT
29330 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
29340 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
29350 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 6(sqlite3_contex
29360 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
29370 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
29380 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
29390 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 esult_error_toob
293a0 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ig(sqlite3_conte
293b0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 xt*);.SQLITE_API
293c0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
293d0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d sult_error_nomem
293e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
293f0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 *);.SQLITE_API v
29400 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
29410 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 lt_error_code(sq
29420 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
29430 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
29440 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
29450 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 sult_int(sqlite3
29460 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b _context*, int);
29470 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
29480 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
29490 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f int64(sqlite3_co
294a0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
294b0 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 int64);.SQLITE_A
294c0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
294d0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 result_null(sqli
294e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 te3_context*);.S
294f0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
29500 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
29510 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt(sqlite3_conte
29520 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
29530 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
29540 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
29550 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
29560 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 result_text16(sq
29570 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
29580 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
29590 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
295a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
295b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
295c0 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 t_text16le(sqlit
295d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
295e0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f st void*, int,vo
295f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 id(*)(void*));.S
29600 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
29610 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
29620 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 xt16be(sqlite3_c
29630 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
29640 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
29650 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
29660 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
29670 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
29680 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
29690 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a , sqlite3_value*
296a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
296b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
296c0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 t_zeroblob(sqlit
296d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
296e0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
296f0 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 3REF: Define New
29700 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 Collating Seque
29710 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 nces {H16600} <S
29720 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20300>.**.** The
29730 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
29740 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 used to add new
29750 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
29760 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b nces to the.** [
29770 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
29780 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 ion] specified a
29790 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
297a0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ment..**.** The
297b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 name of the new
297c0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
297d0 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 ce is specified
297e0 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e as a UTF-8 strin
297f0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 g.** for sqlite3
29800 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
29810 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
29820 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
29830 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 _v2().** and a U
29840 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 TF-16 string for
29850 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
29860 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 collation16(). I
29870 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 n all cases.** t
29880 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 he name is passe
29890 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
298a0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e function argumen
298b0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 t..**.** The thi
298c0 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 rd argument may
298d0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f be one of the co
298e0 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f nstants [SQLITE_
298f0 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 UTF8],.** [SQLIT
29900 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b E_UTF16LE], or [
29910 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
29920 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
29930 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 the user-suppli
29940 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 ed.** routine ex
29950 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 pects to be pass
29960 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 ed pointers to s
29970 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 trings encoded u
29980 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 sing UTF-8,.** U
29990 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 TF-16 little-end
299a0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 ian, or UTF-16 b
299b0 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 ig-endian, respe
299c0 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 ctively. The.**
299d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d third argument m
299e0 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 ight also be [SQ
299f0 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 LITE_UTF16] to i
29a00 6e 64 69 63 61 74 65 20 74 68 61 74 20 74 68 65 ndicate that the
29a10 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 routine.** expe
29a20 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 cts pointers to
29a30 62 65 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 be UTF-16 string
29a40 73 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 s in the native
29a50 62 79 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 byte order, or t
29a60 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 he.** argument c
29a70 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 an be [SQLITE_UT
29a80 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 F16_ALIGNED] if
29a90 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 the.** the routi
29aa0 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 ne expects point
29ab0 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f ers to 16-bit wo
29ac0 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e rd aligned strin
29ad0 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 gs.** of UTF-16
29ae0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
29af0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 te order..**.**
29b00 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
29b10 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 user supplied r
29b20 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 outine must be p
29b30 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 assed as the fif
29b40 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 th.** argument.
29b50 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 If it is NULL,
29b60 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 this is the same
29b70 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 as deleting the
29b80 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
29b90 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 quence (so that
29ba0 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 SQLite cannot ca
29bb0 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a ll it anymore)..
29bc0 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 ** Each time the
29bd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 application sup
29be0 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 plied function i
29bf0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 s invoked, it is
29c00 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 passed.** as it
29c10 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 s first paramete
29c20 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 r a copy of the
29c30 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 void* passed as
29c40 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
29c50 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
29c60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
29c70 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f on() or sqlite3_
29c80 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
29c90 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 16()..**.** The
29ca0 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 remaining argume
29cb0 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 nts to the appli
29cc0 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 cation-supplied
29cd0 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 routine are two
29ce0 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 strings,.** each
29cf0 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
29d00 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 a (length, data)
29d10 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 pair and encode
29d20 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e d in the encodin
29d30 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 g.** that was pa
29d40 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
29d50 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 d argument when
29d60 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 the collation se
29d70 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 quence was.** re
29d80 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 gistered. {END}
29d90 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
29da0 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 defined collati
29db0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c on routine shoul
29dc0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 d.** return nega
29dd0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f tive, zero or po
29de0 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69 sitive if the fi
29df0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 rst string is le
29e00 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 ss than,.** equa
29e10 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 l to, or greater
29e20 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 than the second
29e30 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 string. i.e. (S
29e40 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 TRING1 - STRING2
29e50 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
29e60 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
29e70 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 ation_v2() works
29e80 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 like sqlite3_cr
29e90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
29ea0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
29eb0 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 it takes an extr
29ec0 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 a argument which
29ed0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
29ee0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c for.** the coll
29ef0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 ation. The dest
29f00 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 ructor is called
29f10 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 when the collat
29f20 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f ion is.** destro
29f30 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 yed and is passe
29f40 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 d a copy of the
29f50 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
29f60 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a void* pointer.*
29f70 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
29f80 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
29f90 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 n_v2()..** Colla
29fa0 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f tions are destro
29fb0 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 yed when they ar
29fc0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 e overridden by
29fd0 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 later calls to t
29fe0 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 he.** collation
29ff0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f creation functio
2a000 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b ns or when the [
2a010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2a020 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a ion] is closed.*
2a030 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
2a040 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _close()]..**.**
2a050 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c See also: [sql
2a060 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
2a070 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 eeded()] and [sq
2a080 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
2a090 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a needed16()]..**.
2a0a0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
2a0b0 0a 2a 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 .** [H16603] [H1
2a0c0 36 36 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 6604] [H16606] [
2a0d0 48 31 36 36 30 39 5d 20 5b 48 31 36 36 31 32 5d H16609] [H16612]
2a0e0 20 5b 48 31 36 36 31 35 5d 20 5b 48 31 36 36 31 [H16615] [H1661
2a0f0 38 5d 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 8] [H16621].** [
2a100 48 31 36 36 32 34 5d 20 5b 48 31 36 36 32 37 5d H16624] [H16627]
2a110 20 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a 53 51 4c [H16630].*/.SQL
2a120 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2a130 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
2a140 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a tion(. sqlite3*
2a150 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 , . const char
2a160 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 *zName, . int e
2a170 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
2a180 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 *,. int(*xCompa
2a190 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
2a1a0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
2a1b0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 nst void*).);.SQ
2a1c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2a1d0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
2a1e0 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 ation_v2(. sqli
2a1f0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 te3*, . const c
2a200 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 har *zName, . i
2a210 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
2a220 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 void*,. int(*xC
2a230 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
2a240 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
2a250 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a t,const void*),.
2a260 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 void(*xDestroy
2a270 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 )(void*).);.SQLI
2a280 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2a290 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
2a2a0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 ion16(. sqlite3
2a2b0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 *, . const void
2a2c0 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 *zName,. int e
2a2d0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
2a2e0 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 *,. int(*xCompa
2a2f0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
2a300 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
2a310 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f nst void*).);../
2a320 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
2a330 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 ollation Needed
2a340 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 Callbacks {H1670
2a350 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 0} <S20300>.**.*
2a360 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e * To avoid havin
2a370 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c g to register al
2a380 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 l collation sequ
2a390 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 ences before a d
2a3a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 atabase.** can b
2a3b0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 e used, a single
2a3c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
2a3d0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 on may be regist
2a3e0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a ered with the.**
2a3f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2a400 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c ction] to be cal
2a410 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 led whenever an
2a420 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 undefined collat
2a430 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 ion.** sequence
2a440 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a is required..**.
2a450 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 ** If the functi
2a460 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 on is registered
2a470 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
2a480 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
2a490 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 ded() API,.** th
2a4a0 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 en it is passed
2a4b0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 the names of und
2a4c0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e efined collation
2a4d0 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 sequences as st
2a4e0 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 rings.** encoded
2a4f0 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 in UTF-8. {H167
2a500 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 03} If sqlite3_c
2a510 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
2a520 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 6() is used,.**
2a530 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 the names are pa
2a540 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 ssed as UTF-16 i
2a550 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 n machine native
2a560 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 byte order..**
2a570 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 A call to either
2a580 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 function replac
2a590 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 es any existing
2a5a0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
2a5b0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
2a5c0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 k is invoked, th
2a5d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
2a5e0 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 passed is a cop
2a5f0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f y.** of the seco
2a600 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 nd argument to s
2a610 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
2a620 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 _needed() or.**
2a630 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
2a640 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 n_needed16(). T
2a650 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
2a660 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 nt is the databa
2a670 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
2a680 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
2a690 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 ument is one of
2a6a0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b [SQLITE_UTF8], [
2a6b0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
2a6c0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 .** or [SQLITE_U
2a6d0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 TF16LE], indicat
2a6e0 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 ing the most des
2a6f0 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 irable form of t
2a700 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 he collation.**
2a710 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f sequence functio
2a720 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 n required. The
2a730 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
2a740 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
2a750 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 the.** required
2a760 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
2a770 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 nce..**.** The c
2a780 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
2a790 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 should register
2a7a0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c the desired col
2a7b0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 lation using.**
2a7c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2a7d0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 collation()], [s
2a7e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2a7f0 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 llation16()], or
2a800 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
2a810 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
2a820 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ()]..**.** Requi
2a830 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 rements:.** [H16
2a840 37 30 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48 702] [H16704] [H
2a850 31 36 37 30 36 5d 0a 2a 2f 0a 53 51 4c 49 54 45 16706].*/.SQLITE
2a860 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2a870 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
2a880 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a d(. sqlite3*, .
2a890 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 void*, . void
2a8a0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
2a8b0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
2a8c0 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a const char*).);.
2a8d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2a8e0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
2a8f0 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c _needed16(. sql
2a900 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c ite3*, . void*,
2a910 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a . void(*)(void*
2a920 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 ,sqlite3*,int eT
2a930 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 extRep,const voi
2a940 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 d*).);../*.** Sp
2a950 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f ecify the key fo
2a960 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 r an encrypted d
2a970 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 atabase. This r
2a980 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 outine should be
2a990 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 .** called right
2a9a0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f after sqlite3_o
2a9b0 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 pen()..**.** The
2a9c0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 code to impleme
2a9d0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e nt this API is n
2a9e0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 ot available in
2a9f0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 the public relea
2aa00 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e se.** of SQLite.
2aa10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2aa20 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a nt sqlite3_key(.
2aa30 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2aa40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2aa50 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 /* Database to
2aa60 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 be rekeyed */.
2aa70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 const void *pKey
2aa80 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f , int nKey /
2aa90 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a * The key */.);.
2aaa0 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 ./*.** Change th
2aab0 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e e key on an open
2aac0 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 database. If t
2aad0 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 he current datab
2aae0 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e ase is not.** en
2aaf0 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f crypted, this ro
2ab00 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 utine will encry
2ab10 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d pt it. If pNew=
2ab20 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 =0 or nNew==0, t
2ab30 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 he.** database i
2ab40 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a s decrypted..**.
2ab50 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 ** The code to i
2ab60 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 mplement this AP
2ab70 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 I is not availab
2ab80 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 le in the public
2ab90 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 release.** of S
2aba0 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 QLite..*/.SQLITE
2abb0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2abc0 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 _rekey(. sqlite
2abd0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2abe0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
2abf0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
2ac00 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
2ac10 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
2ac20 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 ey /* The ne
2ac30 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a w key */.);../*.
2ac40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 ** CAPI3REF: Sus
2ac50 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 pend Execution F
2ac60 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 or A Short Time
2ac70 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30 {H10530} <S40410
2ac80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
2ac90 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 te3_sleep() func
2aca0 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 tion causes the
2acb0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 current thread t
2acc0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 o suspend execut
2acd0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 ion.** for at le
2ace0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 ast a number of
2acf0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 milliseconds spe
2ad00 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 cified in its pa
2ad10 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 rameter..**.** I
2ad20 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 f the operating
2ad30 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 system does not
2ad40 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 support sleep re
2ad50 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d quests with.** m
2ad60 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 illisecond time
2ad70 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e resolution, then
2ad80 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 the time will b
2ad90 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a e rounded up to.
2ada0 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 ** the nearest s
2adb0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 econd. The numbe
2adc0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
2add0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 s of sleep actua
2ade0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 lly.** requested
2adf0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 from the operat
2ae00 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 ing system is re
2ae10 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 turned..**.** SQ
2ae20 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 Lite implements
2ae30 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 this interface b
2ae40 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 y calling the xS
2ae50 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 leep().** method
2ae60 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 of the default
2ae70 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
2ae80 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ject..**.** Requ
2ae90 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 33 irements: [H1053
2aea0 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a 53 3] [H10536].*/.S
2aeb0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2aec0 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 lite3_sleep(int)
2aed0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2aee0 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 F: Name Of The F
2aef0 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 older Holding Te
2af00 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48 mporary Files {H
2af10 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 10310} <S20000>.
2af20 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c **.** If this gl
2af30 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 obal variable is
2af40 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
2af50 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 o a string which
2af60 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 is.** the name
2af70 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b of a folder (a.k
2af80 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 .a. directory),
2af90 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 then all tempora
2afa0 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 ry files.** crea
2afb0 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 ted by SQLite wi
2afc0 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 ll be placed in
2afd0 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 that directory.
2afe0 20 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c If this variabl
2aff0 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 e.** is a NULL p
2b000 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
2b010 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 ite performs a s
2b020 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 earch for an app
2b030 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 ropriate.** temp
2b040 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 orary file direc
2b050 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 tory..**.** It i
2b060 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 s not safe to re
2b070 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ad or modify thi
2b080 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f s variable in mo
2b090 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 re than one.** t
2b0a0 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e hread at a time.
2b0b0 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 It is not safe
2b0c0 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 to read or modi
2b0d0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 fy this variable
2b0e0 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 .** if a [databa
2b0f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
2b100 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 s being used at
2b110 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e the same time in
2b120 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 a separate.** t
2b130 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 hread..** It is
2b140 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 intended that th
2b150 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 is variable be s
2b160 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 et once.** as pa
2b170 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e rt of process in
2b180 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 itialization and
2b190 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 before any SQLi
2b1a0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 te interface.**
2b1b0 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 routines have be
2b1c0 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 en called and th
2b1d0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 at this variable
2b1e0 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 remain unchange
2b1f0 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e d.** thereafter.
2b200 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 74 65 6d 70 .**.** The [temp
2b210 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
2b220 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 pragma] may mod
2b230 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c ify this variabl
2b240 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 e and cause.** i
2b250 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 t to point to me
2b260 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
2b270 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
2b280 6f 63 5d 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 oc]. Furthermor
2b290 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f e,.** the [temp_
2b2a0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
2b2b0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 pragma] always a
2b2c0 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 ssumes that any
2b2d0 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 string.** that t
2b2e0 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 his variable poi
2b2f0 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 nts to is held i
2b300 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 n memory obtaine
2b310 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 d from .** [sqli
2b320 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 te3_malloc] and
2b330 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 the pragma may a
2b340 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 ttempt to free t
2b350 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 hat memory.** us
2b360 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
2b370 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 e]..** Hence, if
2b380 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 this variable i
2b390 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 s modified direc
2b3a0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 tly, either it s
2b3b0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 hould be.** made
2b3c0 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f NULL or made to
2b3d0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 point to memory
2b3e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
2b3f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a sqlite3_malloc].
2b400 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 ** or else the u
2b410 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f se of the [temp_
2b420 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
2b430 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 pragma] should b
2b440 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 e avoided..*/.SQ
2b450 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
2b460 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c EXTERN char *sql
2b470 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 ite3_temp_direct
2b480 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ory;../*.** CAPI
2b490 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 3REF: Test For A
2b4a0 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 uto-Commit Mode
2b4b0 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 {H12930} <S60200
2b4c0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
2b4d0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d autocommit mode}
2b4e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2b4f0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 e3_get_autocommi
2b500 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 t() interface re
2b510 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f turns non-zero o
2b520 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 r.** zero if the
2b530 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 given database
2b540 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 connection is or
2b550 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 is not in autoc
2b560 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 ommit mode,.** r
2b570 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 espectively. Au
2b580 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
2b590 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a on by default..
2b5a0 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f ** Autocommit mo
2b5b0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 de is disabled b
2b5c0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 y a [BEGIN] stat
2b5d0 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f ement..** Autoco
2b5e0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d mmit mode is re-
2b5f0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f enabled by a [CO
2b600 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 MMIT] or [ROLLBA
2b610 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 CK]..**.** If ce
2b620 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 rtain kinds of e
2b630 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 rrors occur on a
2b640 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
2b650 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d n a multi-statem
2b660 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 ent.** transacti
2b670 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 on (errors inclu
2b680 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c ding [SQLITE_FUL
2b690 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 L], [SQLITE_IOER
2b6a0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e R],.** [SQLITE_N
2b6b0 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 OMEM], [SQLITE_B
2b6c0 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 USY], and [SQLIT
2b6d0 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 E_INTERRUPT]) th
2b6e0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 en the.** transa
2b6f0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 ction might be r
2b700 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
2b710 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f atically. The o
2b720 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 nly way to.** fi
2b730 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 nd out whether S
2b740 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 QLite automatica
2b750 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 lly rolled back
2b760 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
2b770 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f after.** an erro
2b780 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 r is to use this
2b790 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
2b7a0 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 If another thre
2b7b0 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 ad changes the a
2b7c0 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 utocommit status
2b7d0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2b7e0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 .** connection w
2b7f0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e hile this routin
2b800 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 e is running, th
2b810 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
2b820 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 lue.** is undefi
2b830 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ned..**.** Requi
2b840 72 65 6d 65 6e 74 73 3a 20 5b 48 31 32 39 33 31 rements: [H12931
2b850 5d 20 5b 48 31 32 39 33 32 5d 20 5b 48 31 32 39 ] [H12932] [H129
2b860 33 33 5d 20 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a 33] [H12934].*/.
2b870 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2b880 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 qlite3_get_autoc
2b890 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b ommit(sqlite3*);
2b8a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2b8b0 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 : Find The Datab
2b8c0 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 ase Handle Of A
2b8d0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
2b8e0 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 nt {H13120} <S60
2b8f0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 600>.**.** The s
2b900 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
2b910 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2b920 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 ns the [database
2b930 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
2b940 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 dle.** to which
2b950 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2b960 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 ement] belongs.
2b970 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 The [database c
2b980 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 onnection].** re
2b990 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
2b9a0 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 3_db_handle is t
2b9b0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 he same [databas
2b9c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 e connection] th
2b9d0 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 at was the first
2b9e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
2b9f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
2ba00 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 pare_v2()] call
2ba10 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 (or its variants
2ba20 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 ) that was used
2ba30 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 to.** create the
2ba40 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
2ba50 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
2ba60 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2ba70 73 3a 20 5b 48 31 33 31 32 33 5d 0a 2a 2f 0a 53 s: [H13123].*/.S
2ba80 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
2ba90 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 3 *sqlite3_db_ha
2baa0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d ndle(sqlite3_stm
2bab0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2bac0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 3REF: Find the n
2bad0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 ext prepared sta
2bae0 74 65 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 tement {H13140}
2baf0 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S60600>.**.** T
2bb00 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 his interface re
2bb10 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2bb20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 to the next [pre
2bb30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2bb40 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 after.** pStmt
2bb50 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2bb60 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2bb70 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 nnection] pDb.
2bb80 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c If pStmt is NULL
2bb90 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e .** then this in
2bba0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2bbb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2bbc0 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 first prepared
2bbd0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 statement.** ass
2bbe0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
2bbf0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2bc00 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f tion pDb. If no
2bc10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2bc20 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 ent.** satisfies
2bc30 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 the conditions
2bc40 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c of this routine,
2bc50 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c it returns NULL
2bc60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 ..**.** The [dat
2bc70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2bc80 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 ] pointer D in a
2bc90 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
2bca0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 ite3_next_stmt(D
2bcb0 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 ,S)] must refer
2bcc0 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 to an open datab
2bcd0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
2bce0 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 n and in particu
2bcf0 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 lar must not be
2bd00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
2bd10 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
2bd20 74 73 3a 20 5b 48 31 33 31 34 33 5d 20 5b 48 31 ts: [H13143] [H1
2bd30 33 31 34 36 5d 20 5b 48 31 33 31 34 39 5d 20 5b 3146] [H13149] [
2bd40 48 31 33 31 35 32 5d 0a 2a 2f 0a 53 51 4c 49 54 H13152].*/.SQLIT
2bd50 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 73 74 E_API sqlite3_st
2bd60 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 mt *sqlite3_next
2bd70 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 _stmt(sqlite3 *p
2bd80 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 Db, sqlite3_stmt
2bd90 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2bda0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 CAPI3REF: Commi
2bdb0 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e t And Rollback N
2bdc0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c otification Call
2bdd0 62 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c backs {H12950} <
2bde0 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S60400>.**.** Th
2bdf0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 e sqlite3_commit
2be00 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 _hook() interfac
2be10 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 e registers a ca
2be20 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
2be30 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 on to be invoked
2be40 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e whenever a tran
2be50 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d saction is [COMM
2be60 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e IT | committed].
2be70 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b .** Any callback
2be80 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f set by a previo
2be90 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 us call to sqlit
2bea0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 e3_commit_hook()
2beb0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
2bec0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2bed0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 tion is overridd
2bee0 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 en..** The sqlit
2bef0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
2bf00 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 () interface reg
2bf10 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
2bf20 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f k.** function to
2bf30 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
2bf40 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 ever a transacti
2bf50 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 on is [ROLLBACK
2bf60 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a | rolled back]..
2bf70 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 ** Any callback
2bf80 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 set by a previou
2bf90 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 s call to sqlite
2bfa0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 3_commit_hook().
2bfb0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
2bfc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2bfd0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 ion is overridde
2bfe0 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 n..** The pArg a
2bff0 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 rgument is passe
2c000 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
2c010 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 callback..** If
2c020 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e the callback on
2c030 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 a commit hook f
2c040 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
2c050 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 non-zero,.** the
2c060 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 n the commit is
2c070 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 converted into a
2c080 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a rollback..**.**
2c090 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 If another func
2c0a0 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 tion was previou
2c0b0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 sly registered,
2c0c0 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 its.** pArg valu
2c0d0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 e is returned.
2c0e0 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 Otherwise NULL i
2c0f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
2c100 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 * The callback i
2c110 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 mplementation mu
2c120 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
2c130 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
2c140 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
2c150 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
2c160 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
2c170 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 callback. Any a
2c180 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 ctions.** to mod
2c190 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 ify the database
2c1a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 connection must
2c1b0 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 be deferred unt
2c1c0 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 il after the.**
2c1d0 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 completion of th
2c1e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
2c1f0 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 )] call that tri
2c200 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 ggered the commi
2c210 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b t.** or rollback
2c220 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 hook in the fir
2c230 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 st place..** Not
2c240 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
2c250 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
2c260 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
2c270 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
2c280 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
2c290 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
2c2a0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
2c2b0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
2c2c0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
2c2d0 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 * Registering a
2c2e0 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 NULL function di
2c2f0 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 sables the callb
2c300 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ack..**.** When
2c310 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 the commit hook
2c320 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 callback routine
2c330 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 returns zero, t
2c340 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f he [COMMIT].** o
2c350 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f peration is allo
2c360 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 wed to continue
2c370 6e 6f 72 6d 61 6c 6c 79 2e 20 20 49 66 20 74 68 normally. If th
2c380 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a e commit hook.**
2c390 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
2c3a0 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d o, then the [COM
2c3b0 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 MIT] is converte
2c3c0 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 d into a [ROLLBA
2c3d0 43 4b 5d 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c CK]..** The roll
2c3e0 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 back hook is inv
2c3f0 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 oked on a rollba
2c400 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 ck that results
2c410 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a from a commit.**
2c420 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 hook returning
2c430 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 non-zero, just a
2c440 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 s it would be wi
2c450 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c th any other rol
2c460 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 lback..**.** For
2c470 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 the purposes of
2c480 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 this API, a tra
2c490 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 nsaction is said
2c4a0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a to have been.**
2c4b0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 rolled back if
2c4c0 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c an explicit "ROL
2c4d0 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 LBACK" statement
2c4e0 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 is executed, or
2c4f0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 .** an error or
2c500 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 constraint cause
2c510 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f s an implicit ro
2c520 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e llback to occur.
2c530 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b .** The rollback
2c540 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
2c550 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 invoked if a tr
2c560 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 ansaction is.**
2c570 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f automatically ro
2c580 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 lled back becaus
2c590 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
2c5a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
2c5b0 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c sed..** The roll
2c5c0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 back callback is
2c5d0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 not invoked if
2c5e0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
2c5f0 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 .** rolled back
2c600 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 because a commit
2c610 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
2c620 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 ed non-zero..**
2c630 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 <todo> Check on
2c640 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a this </todo>.**.
2c650 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 ** See also the
2c660 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f [sqlite3_update_
2c670 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 hook()] interfac
2c680 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 e..**.** Require
2c690 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 ments:.** [H1295
2c6a0 31 5d 20 5b 48 31 32 39 35 32 5d 20 5b 48 31 32 1] [H12952] [H12
2c6b0 39 35 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48 953] [H12954] [H
2c6c0 31 32 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 12955].** [H1296
2c6d0 31 5d 20 5b 48 31 32 39 36 32 5d 20 5b 48 31 32 1] [H12962] [H12
2c6e0 39 36 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 963] [H12964].*/
2c6f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
2c700 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 *sqlite3_commit
2c710 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 _hook(sqlite3*,
2c720 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 int(*)(void*), v
2c730 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 oid*);.SQLITE_AP
2c740 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f I void *sqlite3_
2c750 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 rollback_hook(sq
2c760 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 lite3*, void(*)(
2c770 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b void *), void*);
2c780 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2c790 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f : Data Change No
2c7a0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 tification Callb
2c7b0 61 63 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 acks {H12970} <S
2c7c0 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 60400>.**.** The
2c7d0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f sqlite3_update_
2c7e0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 hook() interface
2c7f0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
2c800 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
2c810 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 * with the [data
2c820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2c830 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
2c840 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2c850 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b t.** to be invok
2c860 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f ed whenever a ro
2c870 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e w is updated, in
2c880 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
2c890 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 d..** Any callba
2c8a0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 ck set by a prev
2c8b0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 ious call to thi
2c8c0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f s function.** fo
2c8d0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 r the same datab
2c8e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
2c8f0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a s overridden..**
2c900 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
2c910 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
2c920 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 nter to the func
2c930 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 tion to invoke w
2c940 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 hen a.** row is
2c950 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 updated, inserte
2c960 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a d or deleted..**
2c970 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
2c980 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ent to the callb
2c990 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
2c9a0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
2c9b0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
2c9c0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 3_update_hook().
2c9d0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 .** The second c
2c9e0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 allback argument
2c9f0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 is one of [SQLI
2ca00 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c TE_INSERT], [SQL
2ca10 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 ITE_DELETE],.**
2ca20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 or [SQLITE_UPDAT
2ca30 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e E], depending on
2ca40 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 the operation t
2ca50 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 hat caused the c
2ca60 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 allback.** to be
2ca70 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 invoked..** The
2ca80 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
2ca90 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 h arguments to t
2caa0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 he callback cont
2cab0 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 ain pointers to
2cac0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
2cad0 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 and table name c
2cae0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 ontaining the af
2caf0 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 fected row..** T
2cb00 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 he final callbac
2cb10 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 k parameter is t
2cb20 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 he [rowid] of th
2cb30 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 e row..** In the
2cb40 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 case of an upda
2cb50 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 te, this is the
2cb60 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 [rowid] after th
2cb70 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 e update takes p
2cb80 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lace..**.** The
2cb90 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e update hook is n
2cba0 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 ot invoked when
2cbb0 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 internal system
2cbc0 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f tables are.** mo
2cbd0 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c dified (i.e. sql
2cbe0 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 ite_master and s
2cbf0 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e qlite_sequence).
2cc00 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 63 75 .**.** In the cu
2cc10 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 rrent implementa
2cc20 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 tion, the update
2cc30 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 hook.** is not
2cc40 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 invoked when dup
2cc50 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 lication rows ar
2cc60 65 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 e deleted becaus
2cc70 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 e of an.** [ON C
2cc80 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e ONFLICT | ON CON
2cc90 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 FLICT REPLACE] c
2cca0 6c 61 75 73 65 2e 20 20 4e 6f 72 20 69 73 20 74 lause. Nor is t
2ccb0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a he update hook.*
2ccc0 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 * invoked when r
2ccd0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 ows are deleted
2cce0 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 using the [trunc
2ccf0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
2cd00 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 ]..** The except
2cd10 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 ions defined in
2cd20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d this paragraph m
2cd30 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 ight change in a
2cd40 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 future.** relea
2cd50 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a se of SQLite..**
2cd60 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 .** The update h
2cd70 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ook implementati
2cd80 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 on must not do a
2cd90 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
2cda0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
2cdb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2cdc0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
2cdd0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b the update hook
2cde0 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a . Any actions.*
2cdf0 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 * to modify the
2ce00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2ce10 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 ion must be defe
2ce20 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 rred until after
2ce30 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 the.** completi
2ce40 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 on of the [sqlit
2ce50 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 e3_step()] call
2ce60 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 that triggered t
2ce70 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a he update hook..
2ce80 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
2ce90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2cea0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2ceb0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
2cec0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
2ced0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2cee0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
2cef0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
2cf00 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
2cf10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 ..**.** If anoth
2cf20 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 er function was
2cf30 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 previously regis
2cf40 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 tered, its pArg
2cf50 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 value.** is retu
2cf60 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 rned. Otherwise
2cf70 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
2cf80 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 d..**.** See als
2cf90 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
2cfa0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e ommit_hook()] an
2cfb0 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 d [sqlite3_rollb
2cfc0 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 ack_hook()].** i
2cfd0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a nterfaces..**.**
2cfe0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
2cff0 2a 20 5b 48 31 32 39 37 31 5d 20 5b 48 31 32 39 * [H12971] [H129
2d000 37 33 5d 20 5b 48 31 32 39 37 35 5d 20 5b 48 31 73] [H12975] [H1
2d010 32 39 37 37 5d 20 5b 48 31 32 39 37 39 5d 20 5b 2977] [H12979] [
2d020 48 31 32 39 38 31 5d 20 5b 48 31 32 39 38 33 5d H12981] [H12983]
2d030 20 5b 48 31 32 39 38 36 5d 0a 2a 2f 0a 53 51 4c [H12986].*/.SQL
2d040 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 ITE_API void *sq
2d050 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
2d060 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a k(. sqlite3*, .
2d070 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a void(*)(void *
2d080 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 ,int ,char const
2d090 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c *,char const *,
2d0a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a sqlite3_int64),.
2d0b0 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a void*.);../*.*
2d0c0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
2d0d0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 le Or Disable Sh
2d0e0 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 ared Pager Cache
2d0f0 20 7b 48 31 30 33 33 30 7d 20 3c 53 33 30 39 30 {H10330} <S3090
2d100 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
2d110 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a {shared cache}.*
2d120 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
2d130 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 e enables or dis
2d140 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e ables the sharin
2d150 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 g of the databas
2d160 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 e cache.** and s
2d170 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 chema data struc
2d180 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 tures between [d
2d190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2d1a0 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 on | connections
2d1b0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 ].** to the same
2d1c0 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 database. Shari
2d1d0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 ng is enabled if
2d1e0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 the argument is
2d1f0 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 true.** and dis
2d200 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 abled if the arg
2d210 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a ument is false..
2d220 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 **.** Cache shar
2d230 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 ing is enabled a
2d240 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 nd disabled for
2d250 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 an entire proces
2d260 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 s..** This is a
2d270 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c change as of SQL
2d280 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
2d290 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 0. In prior vers
2d2a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a ions of SQLite,.
2d2b0 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 ** sharing was e
2d2c0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
2d2d0 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 ed for each thre
2d2e0 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a ad separately..*
2d2f0 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 *.** The cache s
2d300 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 haring mode set
2d310 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 by this interfac
2d320 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 e effects all su
2d330 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c bsequent.** call
2d340 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 s to [sqlite3_op
2d350 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
2d360 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 open_v2()], and
2d370 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
2d380 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 )]..** Existing
2d390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2d3a0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 ions continue us
2d3b0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f e the sharing mo
2d3c0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 de.** that was i
2d3d0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 n effect at the
2d3e0 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f time they were o
2d3f0 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 pened..**.** Vir
2d400 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e tual tables cann
2d410 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ot be used with
2d420 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 a shared cache.
2d430 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 When shared.**
2d440 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 cache is enabled
2d450 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 , the [sqlite3_c
2d460 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 reate_module()]
2d470 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 API used to regi
2d480 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 ster.** virtual
2d490 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 tables will alwa
2d4a0 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 ys return an err
2d4b0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 or..**.** This r
2d4c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b outine returns [
2d4d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 SQLITE_OK] if sh
2d4e0 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 ared cache was e
2d4f0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
2d500 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ed.** successful
2d510 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 ly. An [error c
2d520 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
2d530 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a otherwise..**.*
2d540 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 * Shared cache i
2d550 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 s disabled by de
2d560 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 fault. But this
2d570 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a might change in.
2d580 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 ** future releas
2d590 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 es of SQLite. A
2d5a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
2d5b0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 care about shar
2d5c0 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 ed.** cache sett
2d5d0 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 ing should set i
2d5e0 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a t explicitly..**
2d5f0 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b .** See Also: [
2d600 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 SQLite Shared-Ca
2d610 63 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 che Mode].**.**
2d620 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 Requirements: [H
2d630 31 30 33 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 10331] [H10336]
2d640 5b 48 31 30 33 33 37 5d 20 5b 48 31 30 33 33 39 [H10337] [H10339
2d650 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
2d660 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 int sqlite3_enab
2d670 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 le_shared_cache(
2d680 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
2d690 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 I3REF: Attempt T
2d6a0 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f o Free Heap Memo
2d6b0 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 ry {H17340} <S30
2d6c0 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 220>.**.** The s
2d6d0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
2d6e0 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 emory() interfac
2d6f0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 e attempts to fr
2d700 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 ee N bytes.** of
2d710 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 heap memory by
2d720 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e deallocating non
2d730 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 -essential memor
2d740 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a y allocations.**
2d750 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 held by the dat
2d760 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b abase library. {
2d770 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 END} Memory use
2d780 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 d to cache datab
2d790 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 ase.** pages to
2d7a0 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 improve performa
2d7b0 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c nce is an exampl
2d7c0 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 e of non-essenti
2d7d0 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 al memory..** sq
2d7e0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 lite3_release_me
2d7f0 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 mory() returns t
2d800 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2d810 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 es actually free
2d820 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 d,.** which migh
2d830 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 t be more or les
2d840 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e s than the amoun
2d850 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a t requested..**.
2d860 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
2d870 20 5b 48 31 37 33 34 31 5d 20 5b 48 31 37 33 34 [H17341] [H1734
2d880 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 2].*/.SQLITE_API
2d890 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c int sqlite3_rel
2d8a0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 ease_memory(int)
2d8b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2d8c0 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 F: Impose A Limi
2d8d0 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b t On Heap Size {
2d8e0 48 31 37 33 35 30 7d 20 3c 53 33 30 32 32 30 3e H17350} <S30220>
2d8f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2d900 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
2d910 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 it() interface p
2d920 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c laces a "soft" l
2d930 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 imit.** on the a
2d940 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 mount of heap me
2d950 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 mory that may be
2d960 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
2d970 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 Lite..** If an i
2d980 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 nternal allocati
2d990 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 on is requested
2d9a0 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 that would excee
2d9b0 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 d the.** soft he
2d9c0 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 ap limit, [sqlit
2d9d0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
2d9e0 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 y()] is invoked
2d9f0 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 one or.** more t
2da00 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 imes to free up
2da10 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 some space befor
2da20 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e e the allocation
2da30 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a is performed..*
2da40 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 *.** The limit i
2da50 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c s called "soft",
2da60 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c because if [sql
2da70 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
2da80 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 ory()].** cannot
2da90 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 free sufficient
2daa0 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 memory to preve
2dab0 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f nt the limit fro
2dac0 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 m being exceeded
2dad0 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 ,.** the memory
2dae0 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 is allocated any
2daf0 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 way and the curr
2db00 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 ent operation pr
2db10 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 oceeds..**.** A
2db20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f negative or zero
2db30 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 value for N mea
2db40 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 ns that there is
2db50 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 no soft heap li
2db60 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 mit and.** [sqli
2db70 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2db80 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 ry()] will only
2db90 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d be called when m
2dba0 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 emory is exhaust
2dbb0 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 ed..** The defau
2dbc0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 lt value for the
2dbd0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
2dbe0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 is zero..**.**
2dbf0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 SQLite makes a b
2dc00 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f est effort to ho
2dc10 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 nor the soft hea
2dc20 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 p limit..** But
2dc30 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 if the soft heap
2dc40 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 limit cannot be
2dc50 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 honored, execut
2dc60 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 ion will.** cont
2dc70 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 inue without err
2dc80 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 or or notificati
2dc90 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 on. This is why
2dca0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a the limit is.**
2dcb0 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 called a "soft"
2dcc0 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 limit. It is a
2dcd0 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a dvisory only..**
2dce0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c .** Prior to SQL
2dcf0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
2dd00 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 0, this routine
2dd10 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 only constrained
2dd20 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 the memory.** a
2dd30 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 llocated by a si
2dd40 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 ngle thread - th
2dd50 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
2dd60 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 which this rout
2dd70 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 ine.** runs. Be
2dd80 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c ginning with SQL
2dd90 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
2dda0 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 0, the soft heap
2ddb0 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 limit is.** app
2ddc0 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 lied to all thre
2ddd0 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73 ads. The value s
2dde0 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 pecified for the
2ddf0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
2de00 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 .** is an upper
2de10 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 bound on the tot
2de20 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 al memory alloca
2de30 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 tion for all thr
2de40 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 eads. In.** vers
2de50 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 ion 3.5.0 there
2de60 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 is no mechanism
2de70 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 for limiting the
2de80 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a heap usage for.
2de90 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 ** individual th
2dea0 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 reads..**.** Req
2deb0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
2dec0 31 36 33 35 31 5d 20 5b 48 31 36 33 35 32 5d 20 16351] [H16352]
2ded0 5b 48 31 36 33 35 33 5d 20 5b 48 31 36 33 35 34 [H16353] [H16354
2dee0 5d 20 5b 48 31 36 33 35 35 5d 20 5b 48 31 36 33 ] [H16355] [H163
2def0 35 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 58].*/.SQLITE_AP
2df00 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 I void sqlite3_s
2df10 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 oft_heap_limit(i
2df20 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
2df30 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 3REF: Extract Me
2df40 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 tadata About A C
2df50 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 olumn Of A Table
2df60 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 33 30 {H12850} <S6030
2df70 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 0>.**.** This ro
2df80 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 utine returns me
2df90 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 tadata about a s
2dfa0 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f pecific column o
2dfb0 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 f a specific.**
2dfc0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 database table a
2dfd0 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 ccessible using
2dfe0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2dff0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
2e000 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 .** passed as th
2e010 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e e first function
2e020 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
2e030 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 The column is i
2e040 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
2e050 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 second, third a
2e060 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 nd fourth parame
2e070 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 ters to.** this
2e080 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 function. The se
2e090 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
2e0a0 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d s either the nam
2e0b0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
2e0c0 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e e.** (i.e. "main
2e0d0 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 ", "temp" or an
2e0e0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
2e0f0 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 e) containing th
2e100 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 e specified.** t
2e110 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 able or NULL. If
2e120 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 it is NULL, the
2e130 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 n all attached d
2e140 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 atabases are sea
2e150 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 rched.** for the
2e160 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 table using the
2e170 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 same algorithm
2e180 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 used by the data
2e190 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a base engine to.*
2e1a0 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c * resolve unqual
2e1b0 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 ified table refe
2e1c0 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 rences..**.** Th
2e1d0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 e third and four
2e1e0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
2e1f0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 this function a
2e200 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 re the table and
2e210 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 column.** name
2e220 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63 of the desired c
2e230 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 olumn, respectiv
2e240 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 ely. Neither of
2e250 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 these parameters
2e260 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e .** may be NULL.
2e270 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20 .**.** Metadata
2e280 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 is returned by w
2e290 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 riting to the me
2e2a0 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 mory locations p
2e2b0 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68 assed as the 5th
2e2c0 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 .** and subseque
2e2d0 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f nt parameters to
2e2e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 this function.
2e2f0 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 Any of these arg
2e300 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a uments may be.**
2e310 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 NULL, in which
2e320 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 case the corresp
2e330 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f onding element o
2e340 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d f metadata is om
2e350 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c itted..**.** <bl
2e360 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 ockquote>.** <ta
2e370 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a ble border="1">.
2e380 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 ** <tr><th> Para
2e390 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 meter <th> Outpu
2e3a0 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 t<br>Type <th>
2e3b0 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a Description.**.*
2e3c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c * <tr><td> 5th <
2e3d0 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 td> const char*
2e3e0 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a <td> Data type.*
2e3f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c * <tr><td> 6th <
2e400 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 td> const char*
2e410 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 <td> Name of def
2e420 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 ault collation s
2e430 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c equence.** <tr><
2e440 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 td> 7th <td> int
2e450 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 <td> Tr
2e460 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 ue if column has
2e470 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 a NOT NULL cons
2e480 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 traint.** <tr><t
2e490 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 d> 8th <td> int
2e4a0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 <td> Tru
2e4b0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 e if column is p
2e4c0 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 art of the PRIMA
2e4d0 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 RY KEY.** <tr><t
2e4e0 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 d> 9th <td> int
2e4f0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 <td> Tru
2e500 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b e if column is [
2e510 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a AUTOINCREMENT].*
2e520 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f * </table>.** </
2e530 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
2e540 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 * The memory poi
2e550 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 nted to by the c
2e560 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 haracter pointer
2e570 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 s returned for t
2e580 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f he.** declaratio
2e590 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 n type and colla
2e5a0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 tion sequence is
2e5b0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 valid only unti
2e5c0 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 l the next.** ca
2e5d0 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 ll to any SQLite
2e5e0 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a API function..*
2e5f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 *.** If the spec
2e600 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 ified table is a
2e610 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 ctually a view,
2e620 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
2e630 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
2e640 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 ** If the specif
2e650 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 ied column is "r
2e660 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 owid", "oid" or
2e670 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e "_rowid_" and an
2e680 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 .** [INTEGER PRI
2e690 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e MARY KEY] column
2e6a0 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 has been explic
2e6b0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 itly declared, t
2e6c0 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a hen the output.*
2e6d0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 * parameters are
2e6e0 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 set for the exp
2e6f0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
2e700 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 column. If ther
2e710 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 e is no.** expli
2e720 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b citly declared [
2e730 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
2e740 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 KEY] column, the
2e750 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 n the output.**
2e760 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 parameters are s
2e770 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a et as follows:.*
2e780 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 *.** <pre>.**
2e790 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e data type: "IN
2e7a0 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f TEGER".** co
2e7b0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
2e7c0 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 : "BINARY".**
2e7d0 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a not null: 0.**
2e7e0 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 primary key
2e7f0 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 : 1.** auto
2e800 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 increment: 0.**
2e810 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 </pre>.**.** Thi
2e820 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c s function may l
2e830 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 oad one or more
2e840 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 schemas from dat
2e850 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 abase files. If
2e860 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 an.** error occu
2e870 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 rs during this p
2e880 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 rocess, or if th
2e890 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c e requested tabl
2e8a0 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 e or column.** c
2e8b0 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 annot be found,
2e8c0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
2e8d0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
2e8e0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
2e8f0 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 left.** in the
2e900 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2e910 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 tion] (to be ret
2e920 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c rieved using sql
2e930 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a ite3_errmsg())..
2e940 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 **.** This API i
2e950 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
2e960 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 if the library
2e970 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 was compiled wit
2e980 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
2e990 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d _ENABLE_COLUMN_M
2e9a0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 ETADATA] C-prepr
2e9b0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 ocessor symbol d
2e9c0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 efined..*/.SQLIT
2e9d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2e9e0 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 3_table_column_m
2e9f0 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 etadata(. sqlit
2ea00 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2ea10 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 /* Connec
2ea20 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 tion handle */.
2ea30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
2ea40 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 Name, /*
2ea50 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 Database name or
2ea60 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 NULL */. const
2ea70 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d char *zTableNam
2ea80 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 e, /* Table
2ea90 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 name */. const
2eaa0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d char *zColumnNam
2eab0 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 e, /* Column
2eac0 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 name */. char c
2ead0 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 onst **pzDataTyp
2eae0 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a e, /* OUTPUT:
2eaf0 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 Declared data t
2eb00 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f ype */. char co
2eb10 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c nst **pzCollSeq,
2eb20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 /* OUTPUT:
2eb30 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e Collation sequen
2eb40 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 ce name */. int
2eb50 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 *pNotNull,
2eb60 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 /* OUTP
2eb70 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 UT: True if NOT
2eb80 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 NULL constraint
2eb90 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 exists */. int
2eba0 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 *pPrimaryKey,
2ebb0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 /* OUTPU
2ebc0 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d T: True if colum
2ebd0 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a n part of PK */.
2ebe0 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 int *pAutoinc
2ebf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2ec00 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 OUTPUT: True if
2ec10 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d column is auto-
2ec20 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a increment */.);.
2ec30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2ec40 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 Load An Extensi
2ec50 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 30 on {H12600} <S20
2ec60 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 500>.**.** This
2ec70 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 interface loads
2ec80 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 an SQLite extens
2ec90 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d ion library from
2eca0 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e the named file.
2ecb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d 20 .**.** {H12601}
2ecc0 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 The sqlite3_load
2ecd0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 _extension() int
2ece0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
2ecf0 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 20 to load an.**
2ed00 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65 78 SQLite ex
2ed10 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 tension library
2ed20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 contained in the
2ed30 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a file zFile..**.
2ed40 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65 20 ** {H12602} The
2ed50 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a entry point is z
2ed60 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 Proc..**.** {H12
2ed70 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62 603} zProc may b
2ed80 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 e 0, in which ca
2ed90 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 se the name of t
2eda0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a he entry point.*
2edb0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 * defau
2edc0 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f lts to "sqlite3_
2edd0 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e extension_init".
2ede0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d 20 .**.** {H12604}
2edf0 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 The sqlite3_load
2ee00 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 _extension() int
2ee10 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 erface shall ret
2ee20 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 urn.**
2ee30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
2ee40 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 uccess and [SQLI
2ee50 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d TE_ERROR] if som
2ee60 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ething goes wron
2ee70 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 35 g..**.** {H12605
2ee80 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 } If an error oc
2ee90 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 curs and pzErrMs
2eea0 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e g is not 0, then
2eeb0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2eec0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 [sqlite3_load_e
2eed0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 xtension()] inte
2eee0 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 rface shall atte
2eef0 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 mpt to.**
2ef00 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 fill *pzErrMs
2ef10 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 g with error mes
2ef20 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 sage text stored
2ef30 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 in memory.**
2ef40 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 obtained
2ef50 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
2ef60 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 20 lloc()]. {END}
2ef70 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 The calling func
2ef80 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
2ef90 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 should free thi
2efa0 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c s memory by call
2efb0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
2efc0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 e()]..**.** {H12
2efd0 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 606} Extension l
2efe0 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 oading must be e
2eff0 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 nabled using.**
2f000 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
2f010 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 3_enable_load_ex
2f020 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 tension()] prior
2f030 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 to calling this
2f040 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 20 API,.**
2f050 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 otherwise an e
2f060 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 rror will be ret
2f070 75 72 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 urned..*/.SQLITE
2f080 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2f090 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
2f0a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2f0b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 /* Load
2f0c0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 the extension i
2f0d0 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 nto this databas
2f0e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a e connection */.
2f0f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 const char *zF
2f100 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 ile, /* Name
2f110 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 of the shared li
2f120 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 brary containing
2f130 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 extension */.
2f140 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f const char *zPro
2f150 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 c, /* Entry p
2f160 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 oint. Derived f
2f170 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a rom zFile if 0 *
2f180 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 /. char **pzErr
2f190 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 Msg /* Put
2f1a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 error message h
2f1b0 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a ere if not 0 */.
2f1c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2f1d0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 EF: Enable Or Di
2f1e0 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 sable Extension
2f1f0 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 32 30 7d Loading {H12620}
2f200 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20500>.**.**
2f210 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 So as not to ope
2f220 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 n security holes
2f230 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 in older applic
2f240 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a ations that are.
2f250 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f ** unprepared to
2f260 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e deal with exten
2f270 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e sion loading, an
2f280 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 d as a means of
2f290 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 disabling.** ext
2f2a0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 ension loading w
2f2b0 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 hile evaluating
2f2c0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c user-entered SQL
2f2d0 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 , the following
2f2e0 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 API.** is provid
2f2f0 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b ed to turn the [
2f300 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 sqlite3_load_ext
2f310 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e ension()] mechan
2f320 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a ism on and off..
2f330 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 **.** Extension
2f340 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 loading is off b
2f350 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 y default. See t
2f360 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a icket #1863..**.
2f370 2a 2a 20 7b 48 31 32 36 32 31 7d 20 43 61 6c 6c ** {H12621} Call
2f380 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 the sqlite3_ena
2f390 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 ble_load_extensi
2f3a0 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 on() routine wit
2f3b0 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 20 20 h onoff==1.**
2f3c0 20 20 20 20 20 20 20 74 6f 20 74 75 72 6e 20 65 to turn e
2f3d0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 xtension loading
2f3e0 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 on and call it
2f3f0 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f with onoff==0 to
2f400 20 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 turn.**
2f410 20 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 it back off ag
2f420 61 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ain..**.** {H126
2f430 32 32 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 22} Extension lo
2f440 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 ading is off by
2f450 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 53 51 4c 49 default..*/.SQLI
2f460 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2f470 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 e3_enable_load_e
2f480 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 xtension(sqlite3
2f490 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 *db, int onoff)
2f4a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2f4b0 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 F: Automatically
2f4c0 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 Load An Extensi
2f4d0 6f 6e 73 20 7b 48 31 32 36 34 30 7d 20 3c 53 32 ons {H12640} <S2
2f4e0 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0500>.**.** This
2f4f0 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f API can be invo
2f500 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 ked at program s
2f510 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 tartup in order
2f520 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f to register.** o
2f530 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 ne or more stati
2f540 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 cally linked ext
2f550 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c ensions that wil
2f560 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a l be available.*
2f570 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 * to all new [da
2f580 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f590 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a ns]. {END}.**.**
2f5a0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 This routine st
2f5b0 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 ores a pointer t
2f5c0 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 o the extension
2f5d0 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 in an array that
2f5e0 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 is.** obtained
2f5f0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
2f600 6c 6c 6f 63 28 29 5d 2e 20 20 49 66 20 79 6f 75 lloc()]. If you
2f610 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 run a memory le
2f620 61 6b 20 63 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e ak checker.** on
2f630 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e your program an
2f640 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c d it reports a l
2f650 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 eak because of t
2f660 68 69 73 20 61 72 72 61 79 2c 20 69 6e 76 6f 6b his array, invok
2f670 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 e.** [sqlite3_re
2f680 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 set_auto_extensi
2f690 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 73 on()] prior to s
2f6a0 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 hutdown to free
2f6b0 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a the memory..**.*
2f6c0 2a 20 7b 48 31 32 36 34 31 7d 20 54 68 69 73 20 * {H12641} This
2f6d0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
2f6e0 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 rs an extension
2f6f0 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 entry point that
2f700 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
2f710 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e automatically in
2f720 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
2f730 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 new [database c
2f740 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 onnection].**
2f750 20 20 20 20 20 20 20 69 73 20 6f 70 65 6e 65 64 is opened
2f760 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2f770 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
2f780 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 3_open16()],.**
2f790 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c or [sql
2f7a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e ite3_open_v2()].
2f7b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 7d 20 .**.** {H12642}
2f7c0 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 Duplicate extens
2f7d0 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 ions are detecte
2f7e0 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 d so calling thi
2f7f0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 s routine.**
2f800 20 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 20 74 multiple t
2f810 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 imes with the sa
2f820 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 me extension is
2f830 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 harmless..**.**
2f840 7b 48 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f {H12643} This ro
2f850 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 utine stores a p
2f860 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 ointer to the ex
2f870 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 tension in an ar
2f880 72 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ray.**
2f890 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 that is obtained
2f8a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
2f8b0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 alloc()]..**.**
2f8c0 7b 48 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 {H12644} Automat
2f8d0 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 ic extensions ap
2f8e0 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 ply across all t
2f8f0 68 72 65 61 64 73 2e 0a 2a 2f 0a 53 51 4c 49 54 hreads..*/.SQLIT
2f900 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2f910 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 3_auto_extension
2f920 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f (void (*xEntryPo
2f930 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a int)(void));../*
2f940 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
2f950 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 set Automatic Ex
2f960 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 tension Loading
2f970 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30 {H12660} <S20500
2f980 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e >.**.** This fun
2f990 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 ction disables a
2f9a0 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ll previously re
2f9b0 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 gistered automat
2f9c0 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 ic.** extensions
2f9d0 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f . {END} It undo
2f9e0 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 es the effect of
2f9f0 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 all prior.** [s
2fa00 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 qlite3_auto_exte
2fa10 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a nsion()] calls..
2fa20 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54 **.** {H12661} T
2fa30 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 his function dis
2fa40 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f ables all previo
2fa50 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a usly registered.
2fa60 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f ** auto
2fa70 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 matic extensions
2fa80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d ..**.** {H12662}
2fa90 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 This function d
2faa0 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 isables automati
2fab0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 c extensions in
2fac0 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a all threads..*/.
2fad0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
2fae0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 sqlite3_reset_au
2faf0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 to_extension(voi
2fb00 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 d);../*.****** E
2fb10 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 XPERIMENTAL - su
2fb20 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
2fb30 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a without notice *
2fb40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a *************.**
2fb50 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 .** The interfac
2fb60 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c e to the virtual
2fb70 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d -table mechanism
2fb80 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f is currently co
2fb90 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 nsidered.** to b
2fba0 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 e experimental.
2fbb0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d The interface m
2fbc0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 ight change in i
2fbd0 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 ncompatible ways
2fbe0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 ..** If this is
2fbf0 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f a problem for yo
2fc00 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 u, do not use th
2fc10 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 e interface at t
2fc20 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 his time..**.**
2fc30 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c When the virtual
2fc40 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d -table mechanism
2fc50 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 stabilizes, we
2fc60 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 will declare the
2fc70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 .** interface fi
2fc80 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 xed, support it
2fc90 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e indefinitely, an
2fca0 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f d remove this co
2fcb0 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a mment..*/../*.**
2fcc0 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65 64 Structures used
2fcd0 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 by the virtual
2fce0 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a table interface.
2fcf0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
2fd00 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 t sqlite3_vtab s
2fd10 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 qlite3_vtab;.typ
2fd20 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
2fd30 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 te3_index_info s
2fd40 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 qlite3_index_inf
2fd50 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 o;.typedef struc
2fd60 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 t sqlite3_vtab_c
2fd70 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 ursor sqlite3_vt
2fd80 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 ab_cursor;.typed
2fd90 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
2fda0 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 3_module sqlite3
2fdb0 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 _module;../*.**
2fdc0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 CAPI3REF: Virtua
2fdd0 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b l Table Object {
2fde0 48 31 38 30 30 30 7d 20 3c 53 32 30 34 30 30 3e H18000} <S20400>
2fdf0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
2fe00 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 lite3_module {vi
2fe10 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 rtual table modu
2fe20 6c 65 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e le}.** EXPERIMEN
2fe30 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 TAL.**.** This s
2fe40 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 tructure, someti
2fe50 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 mes called a a "
2fe60 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f virtual table mo
2fe70 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e dule", .** defin
2fe80 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 es the implement
2fe90 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 ation of a [virt
2fea0 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a ual tables]. .*
2feb0 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 * This structure
2fec0 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 consists mostly
2fed0 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 of methods for
2fee0 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a the module..**.*
2fef0 2a 20 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c * A virtual tabl
2ff00 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 e module is crea
2ff10 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 ted by filling i
2ff20 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a n a persistent.*
2ff30 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
2ff40 69 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 is structure and
2ff50 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 passing a point
2ff60 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 er to that insta
2ff70 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 nce.** to [sqlit
2ff80 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
2ff90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2ffa0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 create_module_v2
2ffb0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 67 69 ()]..** The regi
2ffc0 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 stration remains
2ffd0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 valid until it
2ffe0 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 is replaced by a
2fff0 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f different.** mo
30000 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 dule or until th
30010 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
30020 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 ection] closes.
30030 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 The content.**
30040 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
30050 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 e must not chang
30060 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72 65 e while it is re
30070 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a gistered with.**
30080 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f any database co
30090 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 nnection..*/.str
300a0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 uct sqlite3_modu
300b0 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 le {. int iVers
300c0 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 ion;. int (*xCr
300d0 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 eate)(sqlite3*,
300e0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 void *pAux,.
300f0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 int a
30100 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 rgc, const char
30110 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 *const*argv,.
30120 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 sqli
30130 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 te3_vtab **ppVTa
30140 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e b, char**);. in
30150 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 t (*xConnect)(sq
30160 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 lite3*, void *pA
30170 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 ux,.
30180 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e int argc, con
30190 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 st char *const*a
301a0 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 rgv,.
301b0 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 sqlite3_vtab
301c0 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a **ppVTab, char*
301d0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 *);. int (*xBes
301e0 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f tIndex)(sqlite3_
301f0 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c vtab *pVTab, sql
30200 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a ite3_index_info*
30210 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 );. int (*xDisc
30220 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f onnect)(sqlite3_
30230 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
30240 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 int (*xDestroy)(
30250 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
30260 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f Tab);. int (*xO
30270 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 pen)(sqlite3_vta
30280 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 b *pVTab, sqlite
30290 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 3_vtab_cursor **
302a0 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 ppCursor);. int
302b0 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 (*xClose)(sqlit
302c0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 e3_vtab_cursor*)
302d0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 ;. int (*xFilte
302e0 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f r)(sqlite3_vtab_
302f0 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 cursor*, int idx
30300 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 Num, const char
30310 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 *idxStr,.
30320 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 int arg
30330 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 c, sqlite3_value
30340 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 **argv);. int
30350 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 (*xNext)(sqlite3
30360 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a _vtab_cursor*);.
30370 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 int (*xEof)(sq
30380 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
30390 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f r*);. int (*xCo
303a0 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 lumn)(sqlite3_vt
303b0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 ab_cursor*, sqli
303c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
303d0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 t);. int (*xRow
303e0 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 id)(sqlite3_vtab
303f0 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 _cursor*, sqlite
30400 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3_int64 *pRowid)
30410 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 ;. int (*xUpdat
30420 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 e)(sqlite3_vtab
30430 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f *, int, sqlite3_
30440 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 value **, sqlite
30450 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 3_int64 *);. in
30460 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 t (*xBegin)(sqli
30470 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 te3_vtab *pVTab)
30480 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
30490 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
304a0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
304b0 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f Commit)(sqlite3_
304c0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
304d0 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 int (*xRollback)
304e0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
304f0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
30500 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 FindFunction)(sq
30510 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 lite3_vtab *pVta
30520 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e b, int nArg, con
30530 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a st 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 20 76 6f 69 64 20 28 2a 2a 70 void (**p
30560 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
30570 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
30580 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
30590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
305a0 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 void **ppAr
305b0 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e g);. int (*xRen
305c0 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ame)(sqlite3_vta
305d0 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 b *pVtab, const
305e0 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a char *zNew);.};.
305f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
30600 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 Virtual Table I
30610 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 ndexing Informat
30620 69 6f 6e 20 7b 48 31 38 31 30 30 7d 20 3c 53 32 ion {H18100} <S2
30630 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
30640 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 S: sqlite3_index
30650 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 49 4d _info.** EXPERIM
30660 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ENTAL.**.** The
30670 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
30680 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 fo structure and
30690 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72 its substructur
306a0 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a es is used to.**
306b0 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f pass informatio
306c0 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 n into and recei
306d0 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f ve the reply fro
306e0 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 m the [xBestInde
306f0 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 x].** method of
30700 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 a [virtual table
30710 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 module]. The f
30720 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e ields under **In
30730 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a puts** are the.*
30740 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 * inputs to xBes
30750 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 tIndex and are r
30760 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 ead-only. xBest
30770 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 Index inserts it
30780 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 s.** results int
30790 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a o the **Outputs*
307a0 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 * fields..**.**
307b0 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b The aConstraint[
307c0 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 ] array records
307d0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e WHERE clause con
307e0 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 straints of the
307f0 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 form:.**.** <pre
30800 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c >column OP expr<
30810 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 /pre>.**.** wher
30820 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c e OP is =, <,
30830 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 <=, >, or
30840 20 26 67 74 3b 3d 2e 20 20 54 68 65 20 70 61 72 >=. The par
30850 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 ticular operator
30860 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e is.** stored in
30870 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f aConstraint[].o
30880 70 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 p. The index of
30890 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 the column is s
308a0 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e tored in.** aCon
308b0 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d straint[].iColum
308c0 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b n. aConstraint[
308d0 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 ].usable is TRUE
308e0 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 if the.** expr
308f0 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e on the right-han
30900 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 d side can be ev
30910 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 aluated (and thu
30920 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 s the constraint
30930 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 .** is usable) a
30940 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 nd false if it c
30950 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 annot..**.** The
30960 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d optimizer autom
30970 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 atically inverts
30980 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f terms of the fo
30990 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 rm "expr OP colu
309a0 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 mn".** and makes
309b0 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 other simplific
309c0 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 ations to the WH
309d0 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e ERE clause in an
309e0 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 attempt to.** g
309f0 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 et as many WHERE
30a00 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e clause terms in
30a10 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 to the form show
30a20 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 n above as possi
30a30 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e ble..** The aCon
30a40 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 straint[] array
30a50 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 only reports WHE
30a60 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 RE clause terms
30a70 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a in the correct.*
30a80 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 * form that refe
30a90 72 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 r to the particu
30aa0 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c lar virtual tabl
30ab0 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e e being queried.
30ac0 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 .**.** Informati
30ad0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 on about the ORD
30ae0 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 ER BY clause is
30af0 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 stored in aOrder
30b00 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 By[]..** Each te
30b10 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 rm of aOrderBy r
30b20 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 ecords a column
30b30 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 of the ORDER BY
30b40 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 clause..**.** Th
30b50 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d e [xBestIndex] m
30b60 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 ethod must fill
30b70 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
30b80 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 [] with informat
30b90 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 ion.** about wha
30ba0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
30bb0 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e pass to xFilter.
30bc0 20 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 If argvIndex>0
30bd0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 then.** the rig
30be0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ht-hand side of
30bf0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
30c00 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 g aConstraint[]
30c10 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 is evaluated.**
30c20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 and becomes the
30c30 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 argvIndex-th ent
30c40 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20 ry in argv. If
30c50 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
30c60 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 [].omit.** is tr
30c70 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e ue, then the con
30c80 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d straint is assum
30c90 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 ed to be fully h
30ca0 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a andled by the.**
30cb0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 virtual table a
30cc0 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 nd is not checke
30cd0 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 d again by SQLit
30ce0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 e..**.** The idx
30cf0 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 Num and idxPtr v
30d00 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 alues are record
30d10 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e ed and passed in
30d20 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 to the.** [xFilt
30d30 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5b er] method..** [
30d40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
30d50 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 is used to free
30d60 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e idxPtr if and on
30d70 6c 79 20 69 66 66 0a 2a 2a 20 6e 65 65 64 54 6f ly iff.** needTo
30d80 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72 FreeIdxPtr is tr
30d90 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 ue..**.** The or
30da0 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 derByConsumed me
30db0 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 ans that output
30dc0 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b from [xFilter]/[
30dd0 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 xNext] will occu
30de0 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 r in.** the corr
30df0 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 ect order to sat
30e00 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 isfy the ORDER B
30e10 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 Y clause so that
30e20 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 no separate.**
30e30 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 sorting step is
30e40 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
30e50 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 The estimatedCos
30e60 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 t value is an es
30e70 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f timate of the co
30e80 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a st of doing the.
30e90 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f ** particular lo
30ea0 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 okup. A full sc
30eb0 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 an of a table wi
30ec0 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f th N entries sho
30ed0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f uld have.** a co
30ee0 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 st of N. A bina
30ef0 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 ry search of a t
30f00 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 able of N entrie
30f10 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a s should have a.
30f20 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f ** cost of appro
30f30 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e ximately log(N).
30f40 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
30f50 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a e3_index_info {.
30f60 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 /* Inputs */.
30f70 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 int nConstraint
30f80 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e ; /* N
30f90 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 umber of entries
30fa0 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 in aConstraint
30fb0 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 */. struct sqli
30fc0 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 te3_index_constr
30fd0 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 aint {. int
30fe0 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 iColumn;
30ff0 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 /* Column
31000 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 on left-hand sid
31010 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 e of constraint
31020 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 */. unsigned
31030 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 char op;
31040 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 /* Constraint
31050 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 operator */.
31060 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 unsigned char u
31070 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 sable; /* Tr
31080 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 ue if this const
31090 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 raint is usable
310a0 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 */. int iTer
310b0 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 mOffset;
310c0 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e /* Used intern
310d0 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 ally - xBestInde
310e0 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 x should ignore
310f0 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 */. } *aConstra
31100 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 int;
31110 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 /* Table of WHER
31120 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 E clause constra
31130 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f ints */. int nO
31140 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 rderBy;
31150 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
31160 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f f terms in the O
31170 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a RDER BY clause *
31180 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 /. struct sqlit
31190 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 e3_index_orderby
311a0 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c {. int iCol
311b0 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 umn;
311c0 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 /* Column numb
311d0 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 er */. unsig
311e0 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 ned char desc;
311f0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 /* True for
31200 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f DESC. False fo
31210 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 r ASC. */. } *a
31220 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 OrderBy;
31230 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 /* The OR
31240 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f DER BY clause */
31250 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f . /* Outputs */
31260 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 . struct sqlite
31270 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 3_index_constrai
31280 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 nt_usage {. i
31290 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 nt argvIndex;
312a0 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 /* if >0
312b0 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 , constraint is
312c0 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 part of argv to
312d0 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 xFilter */. u
312e0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 nsigned char omi
312f0 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f t; /* Do no
31300 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f t code a test fo
31310 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e r this constrain
31320 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 t */. } *aConst
31330 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e raintUsage;. in
31340 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 t idxNum;
31350 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 /* Numb
31360 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 er used to ident
31370 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f ify the index */
31380 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b . char *idxStr;
31390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
313a0 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c String, possibl
313b0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
313c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a sqlite3_malloc *
313d0 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 /. int needToFr
313e0 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f eeIdxStr; /
313f0 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73 * Free idxStr us
31400 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ing sqlite3_free
31410 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 () if true */.
31420 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 int orderByConsu
31430 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 med; /* Tr
31440 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 ue if output is
31450 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 already ordered
31460 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 */. double esti
31470 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 matedCost;
31480 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 /* Estimated cos
31490 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 t of using this
314a0 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 index */.};.#def
314b0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
314c0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 _CONSTRAINT_EQ
314d0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
314e0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
314f0 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 INT_GT 4.#def
31500 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
31510 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 _CONSTRAINT_LE
31520 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8.#define SQLI
31530 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
31540 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 INT_LT 16.#de
31550 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
31560 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 X_CONSTRAINT_GE
31570 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 32.#define SQ
31580 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
31590 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a RAINT_MATCH 64..
315a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
315b0 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 Register A Virtu
315c0 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 al Table Impleme
315d0 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 30 30 7d ntation {H18200}
315e0 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 <S20400>.** EXP
315f0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
31600 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
31610 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 used to register
31620 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 a new [virtual
31630 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 table module] na
31640 6d 65 2e 0a 2a 2a 20 4d 6f 64 75 6c 65 20 6e 61 me..** Module na
31650 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 mes must be regi
31660 73 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a stered before.**
31670 20 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 creating a new
31680 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 [virtual table]
31690 75 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 using the module
316a0 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e , or before usin
316b0 67 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 g a.** preexisti
316c0 6e 67 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ng [virtual tabl
316d0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c e] for the modul
316e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 6f 64 e..**.** The mod
316f0 75 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 ule name is regi
31700 73 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 stered on the [d
31710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
31720 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a on] specified.**
31730 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 by the first pa
31740 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6e 61 rameter. The na
31750 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 me of the module
31760 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 is given by the
31770 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 .** second para
31780 6d 65 74 65 72 2e 20 20 54 68 65 20 74 68 69 72 meter. The thir
31790 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
317a0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 pointer to.** t
317b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
317c0 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 n of the [virtua
317d0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e l table module].
317e0 20 20 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a The fourth.**
317f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e parameter is an
31800 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e arbitrary clien
31810 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 t data pointer t
31820 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68 hat is passed th
31830 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 rough.** into th
31840 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 e [xCreate] and
31850 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f [xConnect] metho
31860 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 ds of the virtua
31870 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a l table module.*
31880 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 * when a new vir
31890 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 tual table is be
318a0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f being created o
318b0 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e r reinitialized.
318c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
318d0 72 66 61 63 65 20 68 61 73 20 65 78 61 63 74 6c rface has exactl
318e0 79 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 y the same effec
318f0 74 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 t as calling.**
31900 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
31910 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 20 77 69 74 module_v2()] wit
31920 68 20 61 20 4e 55 4c 4c 20 63 6c 69 65 6e 74 20 h a NULL client
31930 64 61 74 61 20 64 65 73 74 72 75 63 74 6f 72 2e data destructor.
31940 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 .*/.SQLITE_API S
31950 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
31960 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 AL int sqlite3_c
31970 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 reate_module(.
31980 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
31990 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 /* SQ
319a0 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 Lite connection
319b0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 to register modu
319c0 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e le with */. con
319d0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
319e0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 /* Name
319f0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f of the module */
31a00 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 . const sqlite3
31a10 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a _module *p, /*
31a20 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 Methods for the
31a30 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 module */. voi
31a40 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 d *pClientData
31a50 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e /* Clien
31a60 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 t data for xCrea
31a70 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 te/xConnect */.)
31a80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
31a90 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69 F: Register A Vi
31aa0 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c rtual Table Impl
31ab0 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 ementation {H182
31ac0 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 10} <S20400>.**
31ad0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
31ae0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
31af0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 is identical to
31b00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
31b10 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 ate_module()] me
31b20 74 68 6f 64 2c 0a 2a 2a 20 65 78 63 65 70 74 20 thod,.** except
31b30 74 68 61 74 20 69 74 20 68 61 73 20 61 6e 20 65 that it has an e
31b40 78 74 72 61 20 70 61 72 61 6d 65 74 65 72 20 74 xtra parameter t
31b50 6f 20 73 70 65 63 69 66 79 20 0a 2a 2a 20 61 20 o specify .** a
31b60 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 destructor funct
31b70 69 6f 6e 20 66 6f 72 20 74 68 65 20 63 6c 69 65 ion for the clie
31b80 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e nt data pointer.
31b90 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a SQLite will.**
31ba0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 invoke the dest
31bb0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 ructor function
31bc0 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 (if it is not NU
31bd0 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a LL) when SQLite.
31be0 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 ** no longer nee
31bf0 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 ds the pClientDa
31c00 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 0a 2a 2f ta pointer. .*/
31c10 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
31c20 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
31c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
31c40 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 te_module_v2(.
31c50 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
31c60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 /* SQ
31c70 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 Lite connection
31c80 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 to register modu
31c90 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e le with */. con
31ca0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
31cb0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 /* Name
31cc0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f of the module */
31cd0 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 . const sqlite3
31ce0 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a _module *p, /*
31cf0 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 Methods for the
31d00 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 module */. voi
31d10 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 d *pClientData,
31d20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e /* Clien
31d30 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 t data for xCrea
31d40 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 te/xConnect */.
31d50 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 void(*xDestroy)
31d60 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d (void*) /* M
31d70 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 odule destructor
31d80 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a function */.);.
31d90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
31da0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 Virtual Table I
31db0 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b nstance Object {
31dc0 48 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e H18010} <S20400>
31dd0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
31de0 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58 lite3_vtab.** EX
31df0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
31e00 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 Every [virtual
31e10 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d table module] im
31e20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 plementation use
31e30 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 s a subclass.**
31e40 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
31e50 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 structure to de
31e60 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 scribe a particu
31e70 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 lar instance.**
31e80 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 of the [virtual
31e90 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 table]. Each su
31ea0 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 bclass will.** b
31eb0 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 e tailored to th
31ec0 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
31ed0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 of the module i
31ee0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a mplementation..*
31ef0 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 * The purpose of
31f00 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 this superclass
31f10 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 is to define ce
31f20 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 rtain fields tha
31f30 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 t are.** common
31f40 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d to all module im
31f50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a plementations..*
31f60 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 *.** Virtual tab
31f70 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 les methods can
31f80 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 set an error mes
31f90 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e sage by assignin
31fa0 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 g a.** string ob
31fb0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
31fc0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 ite3_mprintf()]
31fd0 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 to zErrMsg. The
31fe0 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a method should.*
31ff0 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 * take care that
32000 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e any prior strin
32010 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 g is freed by a
32020 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
32030 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f _free()].** prio
32040 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 r to assigning a
32050 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a new string to z
32060 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 ErrMsg. After t
32070 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
32080 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 .** is delivered
32090 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e up to the clien
320a0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 t application, t
320b0 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 he string will b
320c0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
320d0 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 ** freed by sqli
320e0 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 te3_free() and t
320f0 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 he zErrMsg field
32100 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e will be zeroed.
32110 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
32120 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 e3_vtab {. cons
32130 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 t sqlite3_module
32140 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 *pModule; /* T
32150 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 he module for th
32160 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 is virtual table
32170 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 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 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 /* NO LONG
321a0 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 ER USED */. cha
321b0 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 r *zErrMsg;
321c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
321d0 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 Error message fr
321e0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e om sqlite3_mprin
321f0 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 tf() */. /* Vir
32200 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 tual table imple
32210 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 mentations will
32220 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 typically add ad
32230 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 ditional fields
32240 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
32250 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 I3REF: Virtual T
32260 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 able Cursor Obje
32270 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32 ct {H18020} <S2
32280 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
32290 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f S: sqlite3_vtab_
322a0 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 cursor {virtual
322b0 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a table cursor}.**
322c0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
322d0 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 .** Every [virtu
322e0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d al table module]
322f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
32300 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 uses a subclass
32310 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 of the.** follow
32320 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f ing structure to
32330 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 describe cursor
32340 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 s that point int
32350 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 o the.** [virtua
32360 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 l table] and are
32370 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 used.** to loop
32380 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 through the vir
32390 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 tual table. Cur
323a0 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 sors are created
323b0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
323c0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f qlite3_module.xO
323d0 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 pen | xOpen] met
323e0 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c hod of the modul
323f0 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f e and are destro
32400 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 yed.** by the [s
32410 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 qlite3_module.xC
32420 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d lose | xClose] m
32430 65 74 68 6f 64 2e 20 20 43 75 73 73 6f 72 73 20 ethod. Cussors
32440 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 are used.** by t
32450 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 he [xFilter], [x
32460 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b Next], [xEof], [
32470 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 xColumn], and [x
32480 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a Rowid] methods.*
32490 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e * of the module.
324a0 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d Each module im
324b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c plementation wil
324c0 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 l define.** the
324d0 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 content of a cur
324e0 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f sor structure to
324f0 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 suit its own ne
32500 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 eds..**.** This
32510 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 superclass exist
32520 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 s in order to de
32530 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 fine fields of t
32540 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a he cursor that.*
32550 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 * are common to
32560 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 all implementati
32570 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 ons..*/.struct s
32580 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
32590 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 or {. sqlite3_v
325a0 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 tab *pVtab;
325b0 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c /* Virtual tabl
325c0 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 e of this cursor
325d0 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c */. /* Virtual
325e0 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 table implement
325f0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 ations will typi
32600 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 cally add additi
32610 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d onal fields */.}
32620 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
32630 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 F: Declare The S
32640 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 chema Of A Virtu
32650 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30 al Table {H18280
32660 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 } <S20400>.** EX
32670 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
32680 20 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 The [xCreate] a
32690 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 nd [xConnect] me
326a0 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 thods of a.** [v
326b0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
326c0 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 ule] call this i
326d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 nterface.** to d
326e0 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 eclare the forma
326f0 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 t (the names and
32700 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 datatypes of th
32710 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a e columns) of.**
32720 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
32730 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 les they impleme
32740 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 nt..*/.SQLITE_AP
32750 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d I SQLITE_EXPERIM
32760 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 ENTAL int sqlite
32770 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 3_declare_vtab(s
32780 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 qlite3*, const c
32790 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a har *zSQL);../*.
327a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 ** CAPI3REF: Ove
327b0 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e rload A Function
327c0 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 For A Virtual T
327d0 61 62 6c 65 20 7b 48 31 38 33 30 30 7d 20 3c 53 able {H18300} <S
327e0 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20400>.** EXPERI
327f0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 56 69 72 MENTAL.**.** Vir
32800 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 tual tables can
32810 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 provide alternat
32820 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ive implementati
32830 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 ons of functions
32840 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 .** using the [x
32850 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 FindFunction] me
32860 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 thod of the [vir
32870 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
32880 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f e]. .** But glo
32890 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 bal versions of
328a0 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a those functions.
328b0 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e ** must exist in
328c0 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 order to be ove
328d0 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 rloaded..**.** T
328e0 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 his API makes su
328f0 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 re a global vers
32900 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f ion of a functio
32910 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 n with a particu
32920 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 lar.** name and
32930 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 number of parame
32940 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 ters exists. If
32950 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f no such functio
32960 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f n exists.** befo
32970 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63 re this API is c
32980 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e alled, a new fun
32990 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 ction is created
329a0 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 . The implement
329b0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 ation.** of the
329c0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 new function alw
329d0 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 ays causes an ex
329e0 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 ception to be th
329f0 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 rown. So.** the
32a00 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 new function is
32a10 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e not good for an
32a20 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 ything by itself
32a30 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 . Its only.** p
32a40 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 urpose is to be
32a50 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 a placeholder fu
32a60 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 nction that can
32a70 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a be overloaded.**
32a80 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 by a [virtual t
32a90 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 able]..*/.SQLITE
32aa0 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 _API SQLITE_EXPE
32ab0 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c RIMENTAL int sql
32ac0 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 ite3_overload_fu
32ad0 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c nction(sqlite3*,
32ae0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 const char *zFu
32af0 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 ncName, int nArg
32b00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e );../*.** The in
32b10 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 terface to the v
32b20 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 irtual-table mec
32b30 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 hanism defined a
32b40 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a bove (back up.**
32b50 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 to a comment re
32b60 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 markably similar
32b70 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 to this one) is
32b80 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 currently consi
32b90 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 dered.** to be e
32ba0 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 xperimental. Th
32bb0 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 e interface migh
32bc0 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f t change in inco
32bd0 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a mpatible ways..*
32be0 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 * If this is a p
32bf0 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 roblem for you,
32c00 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 do not use the i
32c10 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 nterface at this
32c20 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 time..**.** Whe
32c30 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 n the virtual-ta
32c40 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 ble mechanism st
32c50 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c abilizes, we wil
32c60 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a l declare the.**
32c70 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 interface fixed
32c80 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 , support it ind
32c90 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 efinitely, and r
32ca0 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 emove this comme
32cb0 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 nt..**.****** EX
32cc0 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 PERIMENTAL - sub
32cd0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 ject to change w
32ce0 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a ithout notice **
32cf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a ************.*/.
32d00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
32d10 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 A Handle To An
32d20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 30 Open BLOB {H1780
32d30 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 0} <S30230>.** K
32d40 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 EYWORDS: {BLOB h
32d50 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e andle} {BLOB han
32d60 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 dles}.**.** An i
32d70 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
32d80 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
32d90 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f s an open BLOB o
32da0 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 n which.** [sqli
32db0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
32dc0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
32dd0 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 I/O] can be per
32de0 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 formed..** Objec
32df0 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 ts of this type
32e00 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b are created by [
32e10 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
32e20 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 n()].** and dest
32e30 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
32e40 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 3_blob_close()].
32e50 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
32e60 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e _blob_read()] an
32e70 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f d [sqlite3_blob_
32e80 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 write()] interfa
32e90 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 ces.** can be us
32ea0 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 ed to read or wr
32eb0 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 ite small subsec
32ec0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f tions of the BLO
32ed0 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 B..** The [sqlit
32ee0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d e3_blob_bytes()]
32ef0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
32f00 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 ns the size of t
32f10 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 he BLOB in bytes
32f20 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
32f30 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 uct sqlite3_blob
32f40 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a sqlite3_blob;..
32f50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32f60 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 Open A BLOB For
32f70 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 Incremental I/O
32f80 7b 48 31 37 38 31 30 7d 20 3c 53 33 30 32 33 30 {H17810} <S30230
32f90 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 >.**.** This int
32fa0 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 erfaces opens a
32fb0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 [BLOB handle | h
32fc0 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c andle] to the BL
32fd0 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e OB located.** in
32fe0 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d row iRow, colum
32ff0 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 n zColumn, table
33000 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 zTable in datab
33010 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f ase zDb;.** in o
33020 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
33030 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 same BLOB that w
33040 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 ould be selected
33050 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e by:.**.** <pre>
33060 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a .** SELECT z
33070 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e Column FROM zDb.
33080 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f zTable WHERE [ro
33090 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 wid] = iRow;.**
330a0 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a </pre> {END}.**.
330b0 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 ** If the flags
330c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e parameter is non
330d0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 -zero, then the
330e0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 BLOB is opened f
330f0 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 or read.** and w
33100 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 rite access. If
33110 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 it is zero, the
33120 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 BLOB is opened f
33130 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a or read access..
33140 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 ** It is not pos
33150 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 sible to open a
33160 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 column that is p
33170 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 art of an index
33180 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b or primary .** k
33190 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 ey for writing.
331a0 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 ^If [foreign key
331b0 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 constraints] ar
331c0 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 e enabled, it is
331d0 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c .** not possibl
331e0 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 e to open a colu
331f0 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 mn that is part
33200 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d of a [child key]
33210 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a for writing..**
33220 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 .** Note that th
33230 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 e database name
33240 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e is not the filen
33250 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ame that contain
33260 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 s.** the databas
33270 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 e but rather the
33280 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f symbolic name o
33290 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 f the database t
332a0 68 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e hat.** is assign
332b0 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 ed when the data
332c0 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 base is connecte
332d0 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d d using [ATTACH]
332e0 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61 69 ..** For the mai
332f0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c n database file,
33300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
33310 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a me is "main"..**
33320 20 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 For TEMP tables
33330 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e , the database n
33340 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a ame is "temp"..*
33350 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c *.** On success,
33360 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 [SQLITE_OK] is
33370 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 returned and the
33380 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c new [BLOB handl
33390 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a e] is written.**
333a0 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 to *ppBlob. Oth
333b0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
333c0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
333d0 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 ed and *ppBlob i
333e0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 s set.** to be a
333f0 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 0a 2a null pointer..*
33400 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
33410 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 sets the [databa
33420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 se connection] e
33430 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
33440 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 ssage.** accessi
33450 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 ble via [sqlite3
33460 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 _errcode()] and
33470 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
33480 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a )] and related.*
33490 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 4e 6f * functions. No
334a0 74 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 te that the *ppB
334b0 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 lob variable is
334c0 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a always initializ
334d0 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 ed in a.** way t
334e0 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 hat makes it saf
334f0 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c e to invoke [sql
33500 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 ite3_blob_close(
33510 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a )] on *ppBlob.**
33520 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
33530 68 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 he success or fa
33540 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f ilure of this ro
33550 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 utine..**.** If
33560 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 the row that a B
33570 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 LOB handle point
33580 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 s to is modified
33590 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 by an.** [UPDAT
335a0 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 E], [DELETE], or
335b0 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 by [ON CONFLICT
335c0 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a ] side-effects.*
335d0 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 * then the BLOB
335e0 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 handle is marked
335f0 20 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a as "expired"..*
33600 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 * This is true i
33610 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 f any column of
33620 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 the row is chang
33630 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d ed, even a colum
33640 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 n.** other than
33650 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 the one the BLOB
33660 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 handle is open
33670 6f 6e 2e 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 on..** Calls to
33680 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
33690 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ad()] and [sqlit
336a0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d e3_blob_write()]
336b0 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 for.** a expire
336c0 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 d BLOB handle fa
336d0 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 il with an retur
336e0 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 n code of [SQLIT
336f0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 E_ABORT]..** Cha
33700 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 nges written int
33710 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 o a BLOB prior t
33720 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 o the BLOB expir
33730 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 ing are not.** r
33740 6f 6c 6c 62 61 63 6b 20 62 79 20 74 68 65 20 65 ollback by the e
33750 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 xpiration of the
33760 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 BLOB. Such cha
33770 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 nges will eventu
33780 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 ally.** commit i
33790 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f f the transactio
337a0 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 n continues to c
337b0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a ompletion..**.**
337c0 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 Use the [sqlite
337d0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 3_blob_bytes()]
337e0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74 interface to det
337f0 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20 ermine the size
33800 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 of.** the opened
33810 20 62 6c 6f 62 2e 20 20 54 68 65 20 73 69 7a 65 blob. The size
33820 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e of a blob may n
33830 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 ot be changed by
33840 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 this.** interfa
33850 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50 ce. Use the [UP
33860 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e DATE] SQL comman
33870 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 d to change the
33880 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f size of a.** blo
33890 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 b..**.** The [sq
338a0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
338b0 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 lob()] and [sqli
338c0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 te3_result_zerob
338d0 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65 lob()] interface
338e0 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69 s.** and the bui
338f0 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d lt-in [zeroblob]
33900 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 SQL function ca
33910 6e 20 62 65 20 75 73 65 64 2c 20 69 66 20 64 65 n be used, if de
33920 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 sired,.** to cre
33930 61 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 ate an empty, ze
33940 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 ro-filled blob i
33950 6e 20 77 68 69 63 68 20 74 6f 20 72 65 61 64 20 n which to read
33960 6f 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a or write using.*
33970 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 * this interface
33980 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 ..**.** To avoid
33990 20 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b a resource leak
339a0 2c 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c , every open [BL
339b0 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c OB handle] shoul
339c0 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 d eventually.**
339d0 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 61 be released by a
339e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
339f0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 3_blob_close()].
33a00 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
33a10 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 31 33 5d nts:.** [H17813]
33a20 20 5b 48 31 37 38 31 34 5d 20 5b 48 31 37 38 31 [H17814] [H1781
33a30 36 5d 20 5b 48 31 37 38 31 39 5d 20 5b 48 31 37 6] [H17819] [H17
33a40 38 32 31 5d 20 5b 48 31 37 38 32 34 5d 0a 2a 2f 821] [H17824].*/
33a50 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
33a60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
33a70 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 n(. sqlite3*,.
33a80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
33a90 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
33aa0 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 zTable,. const
33ab0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 char *zColumn,.
33ac0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 sqlite3_int64 i
33ad0 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 Row,. int flags
33ae0 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ,. sqlite3_blob
33af0 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a **ppBlob.);../*
33b00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c .** CAPI3REF: Cl
33b10 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c ose A BLOB Handl
33b20 65 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30 32 e {H17830} <S302
33b30 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 30>.**.** Closes
33b40 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 an open [BLOB h
33b50 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c andle]..**.** Cl
33b60 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 osing a BLOB sha
33b70 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 ll cause the cur
33b80 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e rent transaction
33b90 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 to commit.** if
33ba0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 there are no ot
33bb0 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 her BLOBs, no pe
33bc0 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 nding prepared s
33bd0 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 tatements, and t
33be0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
33bf0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 onnection is in
33c00 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 [autocommit mode
33c10 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72 69 ]..** If any wri
33c20 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f tes were made to
33c30 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 the BLOB, they
33c40 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e might be held in
33c50 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 cache.** until
33c60 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 the close operat
33c70 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c ion if they will
33c80 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 fit..**.** Clos
33c90 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 ing the BLOB oft
33ca0 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 en forces the ch
33cb0 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 anges.** out to
33cc0 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 disk and so if a
33cd0 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 ny I/O errors oc
33ce0 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c cur, they will l
33cf0 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 ikely occur.** a
33d00 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 t the time when
33d10 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 the BLOB is clos
33d20 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20 ed. Any errors
33d30 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e that occur durin
33d40 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 g.** closing are
33d50 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e reported as a n
33d60 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 on-zero return v
33d70 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 alue..**.** The
33d80 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 BLOB is closed u
33d90 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 nconditionally.
33da0 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f Even if this ro
33db0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a utine returns.**
33dc0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 an error code,
33dd0 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c the BLOB is stil
33de0 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 l closed..**.**
33df0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 Calling this rou
33e00 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c tine with a null
33e10 20 70 6f 69 6e 74 65 72 20 28 77 68 69 63 68 20 pointer (which
33e20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 as would be retu
33e30 72 6e 65 64 0a 2a 2a 20 62 79 20 66 61 69 6c 65 rned.** by faile
33e40 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 d call to [sqlit
33e50 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 e3_blob_open()])
33e60 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e is a harmless n
33e70 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 o-op..**.** Requ
33e80 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
33e90 37 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b 7833] [H17836] [
33ea0 48 31 37 38 33 39 5d 0a 2a 2f 0a 53 51 4c 49 54 H17839].*/.SQLIT
33eb0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
33ec0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 3_blob_close(sql
33ed0 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f ite3_blob *);../
33ee0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
33ef0 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f eturn The Size O
33f00 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b f An Open BLOB {
33f10 48 31 37 38 34 30 7d 20 3c 53 33 30 32 33 30 3e H17840} <S30230>
33f20 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 .**.** Returns t
33f30 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 he size in bytes
33f40 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 of the BLOB acc
33f50 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 essible via the
33f60 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 .** successfully
33f70 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 opened [BLOB ha
33f80 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c ndle] in its onl
33f90 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 y argument. The
33fa0 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 .** incremental
33fb0 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 blob I/O routine
33fc0 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 s can only read
33fd0 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65 or overwriting e
33fe0 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 xisting.** blob
33ff0 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61 content; they ca
34000 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 nnot change the
34010 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a size of a blob..
34020 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
34030 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e ne only works on
34040 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d a [BLOB handle]
34050 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 which has been
34060 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 created.** by a
34070 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c prior successful
34080 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
34090 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 3_blob_open()] a
340a0 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 nd which has not
340b0 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 .** been closed
340c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 by [sqlite3_blob
340d0 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 _close()]. Pass
340e0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f ing any other po
340f0 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 inter in.** to t
34100 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 his routine resu
34110 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 lts in undefined
34120 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e and probably un
34130 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 desirable behavi
34140 6f 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 or..**.** Requir
34150 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 ements:.** [H178
34160 34 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 43].*/.SQLITE_AP
34170 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c I int sqlite3_bl
34180 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ob_bytes(sqlite3
34190 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _blob *);../*.**
341a0 20 43 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 CAPI3REF: Read
341b0 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 Data From A BLOB
341c0 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b Incrementally {
341d0 48 31 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e H17850} <S30230>
341e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
341f0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
34200 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 read data from a
34210 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e n open [BLOB han
34220 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 dle] into a.** c
34230 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 aller-supplied b
34240 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f uffer. N bytes o
34250 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 f data are copie
34260 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a d into buffer Z.
34270 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e ** from the open
34280 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 BLOB, starting
34290 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 at offset iOffse
342a0 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 t..**.** If offs
342b0 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 et iOffset is le
342c0 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 ss than N bytes
342d0 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 from the end of
342e0 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 the BLOB,.** [SQ
342f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 LITE_ERROR] is r
34300 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 eturned and no d
34310 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 ata is read. If
34320 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 N or iOffset is
34330 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 .** less than ze
34340 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ro, [SQLITE_ERRO
34350 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 R] is returned a
34360 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 nd no data is re
34370 61 64 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 ad..** The size
34380 6f 66 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 of the blob (and
34390 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d hence the maxim
343a0 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f um value of N+iO
343b0 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 ffset).** can be
343c0 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e determined usin
343d0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 g the [sqlite3_b
343e0 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 lob_bytes()] int
343f0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e erface..**.** An
34400 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 attempt to read
34410 20 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 from an expired
34420 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 [BLOB handle] f
34430 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 ails with an.**
34440 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 error code of [S
34450 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a QLITE_ABORT]..**
34460 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 .** On success,
34470 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 SQLITE_OK is ret
34480 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 urned..** Otherw
34490 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 ise, an [error c
344a0 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 ode] or an [exte
344b0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
344c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
344d0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
344e0 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 only works on a
344f0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 [BLOB handle] w
34500 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 hich has been cr
34510 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 eated.** by a pr
34520 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
34530 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
34540 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 blob_open()] and
34550 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a which has not.*
34560 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 * been closed by
34570 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 [sqlite3_blob_c
34580 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e lose()]. Passin
34590 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e g any other poin
345a0 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 ter in.** to thi
345b0 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 s routine result
345c0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 s in undefined a
345d0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 nd probably unde
345e0 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 sirable behavior
345f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
34600 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f : [sqlite3_blob_
34610 77 72 69 74 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 write()]..**.**
34620 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
34630 20 5b 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 [H17853] [H1785
34640 36 5d 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 6] [H17859] [H17
34650 38 36 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 862] [H17863] [H
34660 31 37 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 17865] [H17868].
34670 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
34680 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 t sqlite3_blob_r
34690 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ead(sqlite3_blob
346a0 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 *, void *Z, int
346b0 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 N, int iOffset)
346c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
346d0 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e F: Write Data In
346e0 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d to A BLOB Increm
346f0 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d entally {H17870}
34700 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 <S30230>.**.**
34710 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 This function is
34720 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 used to write d
34730 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e ata into an open
34740 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 [BLOB handle] f
34750 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d rom a.** caller-
34760 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e supplied buffer.
34770 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 N bytes of data
34780 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d are copied from
34790 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a the buffer Z.**
347a0 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 into the open B
347b0 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 LOB, starting at
347c0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e offset iOffset.
347d0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 .**.** If the [B
347e0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 LOB handle] pass
347f0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
34800 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 argument was not
34810 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 opened for.** w
34820 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 riting (the flag
34830 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b s parameter to [
34840 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
34850 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a n()] was zero),.
34860 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ** this function
34870 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
34880 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a _READONLY]..**.*
34890 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
348a0 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 may only modify
348b0 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 the contents of
348c0 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a the BLOB; it is.
348d0 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 ** not possible
348e0 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 to increase the
348f0 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 size of a BLOB u
34900 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a sing this API..*
34910 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 * If offset iOff
34920 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e set is less than
34930 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 N bytes from th
34940 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f e end of the BLO
34950 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 B,.** [SQLITE_ER
34960 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ROR] is returned
34970 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 and no data is
34980 77 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 written. If N i
34990 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a s.** less than z
349a0 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ero [SQLITE_ERRO
349b0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 R] is returned a
349c0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 nd no data is wr
349d0 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 itten..** The si
349e0 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 ze of the BLOB (
349f0 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 and hence the ma
34a00 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e ximum value of N
34a10 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e +iOffset).** can
34a20 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 be determined u
34a30 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 sing the [sqlite
34a40 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 3_blob_bytes()]
34a50 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
34a60 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 An attempt to w
34a70 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 rite to an expir
34a80 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d ed [BLOB handle]
34a90 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a fails with an.*
34aa0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 * error code of
34ab0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 [SQLITE_ABORT].
34ac0 20 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 Writes to the B
34ad0 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 LOB that occurre
34ae0 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 d.** before the
34af0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 [BLOB handle] ex
34b00 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f pired are not ro
34b10 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 lled back by the
34b20 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f .** expiration o
34b30 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 f the handle, th
34b40 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 ough of course t
34b50 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 hose changes mig
34b60 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 ht.** have been
34b70 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 overwritten by t
34b80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 he statement tha
34b90 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c t expired the BL
34ba0 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 OB handle.** or
34bb0 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e by other indepen
34bc0 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e dent statements.
34bd0 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 .**.** On succes
34be0 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 s, SQLITE_OK is
34bf0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 returned..** Oth
34c00 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 erwise, an [err
34c10 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b or code] or an [
34c20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
34c30 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
34c40 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
34c50 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 tine only works
34c60 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c on a [BLOB handl
34c70 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 e] which has bee
34c80 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 n created.** by
34c90 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 a prior successf
34ca0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
34cb0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d te3_blob_open()]
34cc0 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e and which has n
34cd0 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 ot.** been close
34ce0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c d by [sqlite3_bl
34cf0 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 ob_close()]. Pa
34d00 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 ssing any other
34d10 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f pointer in.** to
34d20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 this routine re
34d30 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e sults in undefin
34d40 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 ed and probably
34d50 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 undesirable beha
34d60 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 vior..**.** See
34d70 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
34d80 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a lob_read()]..**.
34d90 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
34da0 0a 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 .** [H17873] [H1
34db0 37 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 7874] [H17875] [
34dc0 48 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d H17876] [H17877]
34dd0 20 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38 [H17879] [H1788
34de0 32 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 2] [H17885].** [
34df0 48 31 37 38 38 38 5d 0a 2a 2f 0a 53 51 4c 49 54 H17888].*/.SQLIT
34e00 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
34e10 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 3_blob_write(sql
34e20 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e ite3_blob *, con
34e30 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 st void *z, int
34e40 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b n, int iOffset);
34e50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
34e60 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 : Virtual File S
34e70 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 20 7b 48 ystem Objects {H
34e80 31 31 32 30 30 7d 20 3c 53 32 30 31 30 30 3e 0a 11200} <S20100>.
34e90 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 **.** A virtual
34ea0 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 filesystem (VFS)
34eb0 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f is an [sqlite3_
34ec0 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 vfs] object.** t
34ed0 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 hat SQLite uses
34ee0 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 to interact.** w
34ef0 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 ith the underlyi
34f00 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
34f10 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 tem. Most SQLit
34f20 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 e builds come wi
34f30 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 th a.** single d
34f40 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 efault VFS that
34f50 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 is appropriate f
34f60 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 or the host comp
34f70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 uter..** New VFS
34f80 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 es can be regist
34f90 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e ered and existin
34fa0 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 g VFSes can be u
34fb0 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 nregistered..**
34fc0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e The following in
34fd0 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f terfaces are pro
34fe0 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 vided..**.** The
34ff0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e sqlite3_vfs_fin
35000 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 d() interface re
35010 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
35020 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 to a VFS given i
35030 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 4e 61 6d 65 ts name..** Name
35040 73 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 s are case sensi
35050 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 tive..** Names a
35060 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 re zero-terminat
35070 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 ed UTF-8 strings
35080 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 ..** If there is
35090 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c no match, a NUL
350a0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
350b0 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 7a 56 66 urned..** If zVf
350c0 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 sName is NULL th
350d0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 en the default V
350e0 46 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a FS is returned..
350f0 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 **.** New VFSes
35100 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77 are registered w
35110 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f ith sqlite3_vfs_
35120 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 45 register()..** E
35130 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f ach new VFS beco
35140 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 mes the default
35150 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 VFS if the makeD
35160 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e flt flag is set.
35170 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20 56 46 53 .** The same VFS
35180 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 can be register
35190 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ed multiple time
351a0 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 s without injury
351b0 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 ..** To make an
351c0 65 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 existing VFS int
351d0 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 o the default VF
351e0 53 2c 20 72 65 67 69 73 74 65 72 20 69 74 20 61 S, register it a
351f0 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 gain.** with the
35200 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 makeDflt flag s
35210 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66 et. If two diff
35220 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 erent VFSes with
35230 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d the.** same nam
35240 65 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 e are registered
35250 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 , the behavior i
35260 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 s undefined. If
35270 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 a.** VFS is reg
35280 69 73 74 65 72 65 64 20 77 69 74 68 20 61 20 6e istered with a n
35290 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c ame that is NULL
352a0 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 or an empty str
352b0 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ing,.** then the
352c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
352d0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e efined..**.** Un
352e0 72 65 67 69 73 74 65 72 20 61 20 56 46 53 20 77 register a VFS w
352f0 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f ith the sqlite3_
35300 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 vfs_unregister()
35310 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 interface..** I
35320 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 f the default VF
35330 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 S is unregistere
35340 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 d, another VFS i
35350 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 s chosen as.** t
35360 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 he default. The
35370 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 choice for the
35380 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74 new VFS is arbit
35390 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 rary..**.** Requ
353a0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
353b0 31 32 30 33 5d 20 5b 48 31 31 32 30 36 5d 20 5b 1203] [H11206] [
353c0 48 31 31 32 30 39 5d 20 5b 48 31 31 32 31 32 5d H11209] [H11212]
353d0 20 5b 48 31 31 32 31 35 5d 20 5b 48 31 31 32 31 [H11215] [H1121
353e0 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 8].*/.SQLITE_API
353f0 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 sqlite3_vfs *sq
35400 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 lite3_vfs_find(c
35410 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e onst char *zVfsN
35420 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ame);.SQLITE_API
35430 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 int sqlite3_vfs
35440 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 _register(sqlite
35450 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 3_vfs*, int make
35460 44 66 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 Dflt);.SQLITE_AP
35470 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 I int sqlite3_vf
35480 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c s_unregister(sql
35490 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a ite3_vfs*);../*.
354a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
354b0 65 78 65 73 20 7b 48 31 37 30 30 30 7d 20 3c 53 exes {H17000} <S
354c0 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20000>.**.** The
354d0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 SQLite core use
354e0 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 s these routines
354f0 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 for thread.** s
35500 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 ynchronization.
35510 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 Though they are
35520 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 intended for int
35530 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 ernal.** use by
35540 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 SQLite, code tha
35550 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 t links against
35560 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 SQLite is.** per
35570 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e mitted to use an
35580 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
35590 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 nes..**.** The S
355a0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 QLite source cod
355b0 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 e contains multi
355c0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
355d0 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 ons.** of these
355e0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 mutex routines.
355f0 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 An appropriate
35600 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a implementation.*
35610 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 * is selected au
35620 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 tomatically at c
35630 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 ompile-time. Th
35640 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 e following.** i
35650 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 mplementations a
35660 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 re available in
35670 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a the SQLite core:
35680 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
35690 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 li> SQLITE_MUT
356a0 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 EX_OS2.** <li>
356b0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 SQLITE_MUTEX_PT
356c0 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 HREAD.** <li>
356d0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 SQLITE_MUTEX_W32
356e0 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 .** <li> SQLIT
356f0 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 E_MUTEX_NOOP.**
35700 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
35710 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f SQLITE_MUTEX_NOO
35720 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e P implementation
35730 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 is a set of rou
35740 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f tines.** that do
35750 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 es no real locki
35760 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70 ng and is approp
35770 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e riate for use in
35780 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 .** a single-thr
35790 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f eaded applicatio
357a0 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4d n. The SQLITE_M
357b0 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c UTEX_OS2,.** SQL
357c0 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 ITE_MUTEX_PTHREA
357d0 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 D, and SQLITE_MU
357e0 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e TEX_W32 implemen
357f0 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 tations.** are a
35800 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 ppropriate for u
35810 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 se on OS/2, Unix
35820 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a , and Windows..*
35830 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 69 *.** If SQLite i
35840 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
35850 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 the SQLITE_MUTEX
35860 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 _APPDEF preproce
35870 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 ssor.** macro de
35880 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 fined (with "-DS
35890 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 QLITE_MUTEX_APPD
358a0 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 EF=1"), then no
358b0 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 mutex.** impleme
358c0 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 ntation is inclu
358d0 64 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 ded with the lib
358e0 72 61 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61 rary. In this ca
358f0 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 se the.** applic
35900 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c ation must suppl
35910 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 y a custom mutex
35920 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35930 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 using the.** [SQ
35940 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
35950 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 X] option of the
35960 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
35970 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 ) function.** be
35980 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c fore calling sql
35990 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
359a0 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70 ) or any other p
359b0 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a ublic sqlite3_.*
359c0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 * function that
359d0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e calls sqlite3_in
359e0 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a itialize()..**.*
359f0 2a 20 7b 48 31 37 30 31 31 7d 20 54 68 65 20 73 * {H17011} The s
35a00 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
35a10 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c oc() routine all
35a20 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 ocates a new.**
35a30 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e mutex and return
35a40 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 s a pointer to i
35a50 74 2e 20 7b 48 31 37 30 31 32 7d 20 49 66 20 69 t. {H17012} If i
35a60 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a t returns NULL.*
35a70 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 * that means tha
35a80 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 t a mutex could
35a90 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 not be allocated
35aa0 2e 20 7b 48 31 37 30 31 33 7d 20 53 51 4c 69 74 . {H17013} SQLit
35ab0 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 e.** will unwind
35ac0 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 its stack and r
35ad0 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 eturn an error.
35ae0 7b 48 31 37 30 31 34 7d 20 54 68 65 20 61 72 67 {H17014} The arg
35af0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 ument.** to sqli
35b00 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
35b10 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 ) is one of thes
35b20 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
35b30 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a nts:.**.** <ul>.
35b40 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
35b50 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c MUTEX_FAST.** <l
35b60 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 i> SQLITE_MUTEX
35b70 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c _RECURSIVE.** <l
35b80 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 i> SQLITE_MUTEX
35b90 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a _STATIC_MASTER.*
35ba0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
35bb0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a UTEX_STATIC_MEM.
35bc0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
35bd0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
35be0 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 2.** <li> SQLIT
35bf0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 E_MUTEX_STATIC_P
35c00 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c RNG.** <li> SQL
35c10 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
35c20 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 _LRU.** <li> SQ
35c30 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
35c40 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 0a C_LRU2.** </ul>.
35c50 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 35 7d 20 54 **.** {H17015} T
35c60 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e he first two con
35c70 73 74 61 6e 74 73 20 63 61 75 73 65 20 73 71 6c stants cause sql
35c80 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
35c90 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 () to create.**
35ca0 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54 68 a new mutex. Th
35cb0 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72 e new mutex is r
35cc0 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53 51 ecursive when SQ
35cd0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
35ce0 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 SIVE.** is used
35cf0 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 but not necessar
35d00 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 ily so when SQLI
35d10 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73 TE_MUTEX_FAST is
35d20 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 used. {END}.**
35d30 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d The mutex implem
35d40 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f entation does no
35d50 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 t need to make a
35d60 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 distinction.**
35d70 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d between SQLITE_M
35d80 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61 UTEX_RECURSIVE a
35d90 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f nd SQLITE_MUTEX_
35da0 46 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a FAST if it does.
35db0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 ** not want to.
35dc0 20 7b 48 31 37 30 31 36 7d 20 42 75 74 20 53 51 {H17016} But SQ
35dd0 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 Lite will only r
35de0 65 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69 equest a recursi
35df0 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 ve mutex in.** c
35e00 61 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65 ases where it re
35e10 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 ally needs one.
35e20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66 61 73 74 {END} If a fast
35e30 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 er non-recursive
35e40 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d mutex.** implem
35e50 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 entation is avai
35e60 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 lable on the hos
35e70 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 t platform, the
35e80 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a mutex subsystem.
35e90 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 ** might return
35ea0 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 such a mutex in
35eb0 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 response to SQLI
35ec0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a TE_MUTEX_FAST..*
35ed0 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 7d 20 54 68 *.** {H17017} Th
35ee0 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 e other allowed
35ef0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73 71 parameters to sq
35f00 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
35f10 63 28 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a c() each return.
35f20 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
35f30 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69 73 a static preexis
35f40 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45 4e 44 ting mutex. {END
35f50 7d 20 20 53 69 78 20 73 74 61 74 69 63 20 6d 75 } Six static mu
35f60 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 texes are.** use
35f70 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 d by the current
35f80 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 version of SQLi
35f90 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 te. Future vers
35fa0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a ions of SQLite.*
35fb0 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 * may add additi
35fc0 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 onal static mute
35fd0 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 xes. Static mut
35fe0 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 exes are for int
35ff0 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 ernal.** use by
36000 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 SQLite only. Ap
36010 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
36020 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 use SQLite mutex
36030 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 es should.** use
36040 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 only the dynami
36050 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e c mutexes return
36060 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 ed by SQLITE_MUT
36070 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 EX_FAST or.** SQ
36080 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
36090 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 SIVE..**.** {H17
360a0 30 31 38 7d 20 4e 6f 74 65 20 74 68 61 74 20 69 018} Note that i
360b0 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e f one of the dyn
360c0 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d amic mutex param
360d0 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 eters (SQLITE_MU
360e0 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 TEX_FAST.** or S
360f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
36100 52 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 RSIVE) is used t
36110 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 hen sqlite3_mute
36120 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 x_alloc().** ret
36130 75 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 urns a different
36140 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 mutex on every
36150 63 61 6c 6c 2e 20 20 7b 48 31 37 30 33 34 7d 20 call. {H17034}
36160 42 75 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 But for the stat
36170 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 ic.** mutex type
36180 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 s, the same mute
36190 78 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e x is returned on
361a0 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 every call that
361b0 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 has.** the same
361c0 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a type number..**
361d0 0a 2a 2a 20 7b 48 31 37 30 31 39 7d 20 54 68 65 .** {H17019} The
361e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 sqlite3_mutex_f
361f0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 ree() routine de
36200 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 allocates a prev
36210 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 iously.** alloca
36220 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 ted dynamic mute
36230 78 2e 20 7b 48 31 37 30 32 30 7d 20 53 51 4c 69 x. {H17020} SQLi
36240 74 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f te is careful to
36250 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 deallocate ever
36260 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 y.** dynamic mut
36270 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 ex that it alloc
36280 61 74 65 73 2e 20 7b 41 31 37 30 32 31 7d 20 54 ates. {A17021} T
36290 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 he dynamic mutex
362a0 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 es must not be i
362b0 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 n.** use when th
362c0 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 ey are deallocat
362d0 65 64 2e 20 7b 41 31 37 30 32 32 7d 20 41 74 74 ed. {A17022} Att
362e0 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c empting to deall
362f0 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a ocate a static.*
36300 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 * mutex results
36310 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
36320 61 76 69 6f 72 2e 20 7b 48 31 37 30 32 33 7d 20 avior. {H17023}
36330 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 SQLite never dea
36340 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 llocates.** a st
36350 61 74 69 63 20 6d 75 74 65 78 2e 20 7b 45 4e 44 atic mutex. {END
36360 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 }.**.** The sqli
36370 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 te3_mutex_enter(
36380 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 ) and sqlite3_mu
36390 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e tex_try() routin
363a0 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f es attempt.** to
363b0 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 enter a mutex.
363c0 7b 48 31 37 30 32 34 7d 20 49 66 20 61 6e 6f 74 {H17024} If anot
363d0 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61 6c her thread is al
363e0 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 65 ready within the
363f0 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 mutex,.** sqlit
36400 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 e3_mutex_enter()
36410 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 will block and
36420 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
36430 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a y() will return.
36440 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 ** SQLITE_BUSY.
36450 7b 48 31 37 30 32 35 7d 20 20 54 68 65 20 73 71 {H17025} The sq
36460 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
36470 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
36480 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a rns [SQLITE_OK].
36490 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 ** upon successf
364a0 75 6c 20 65 6e 74 72 79 2e 20 20 7b 48 31 37 30 ul entry. {H170
364b0 32 36 7d 20 4d 75 74 65 78 65 73 20 63 72 65 61 26} Mutexes crea
364c0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c ted using.** SQL
364d0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
364e0 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 IVE can be enter
364f0 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ed multiple time
36500 73 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 s by the same th
36510 72 65 61 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 37 read..** {H17027
36520 7d 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 } In such cases
36530 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 the,.** mutex mu
36540 73 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 st be exited an
36550 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 equal number of
36560 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f times before ano
36570 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 ther thread.** c
36580 61 6e 20 65 6e 74 65 72 2e 20 20 7b 41 31 37 30 an enter. {A170
36590 32 38 7d 20 49 66 20 74 68 65 20 73 61 6d 65 20 28} If the same
365a0 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 thread tries to
365b0 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a enter any other.
365c0 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 ** kind of mutex
365d0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c more than once,
365e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
365f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 7b undefined..** {
36600 48 31 37 30 32 39 7d 20 53 51 4c 69 74 65 20 77 H17029} SQLite w
36610 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 ill never exhibi
36620 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 t.** such behavi
36630 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 or in its own us
36640 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a e of mutexes..**
36650 0a 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 .** Some systems
36660 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 (for example, W
36670 69 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f indows 95) do no
36680 74 20 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 t support the op
36690 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 eration.** imple
366a0 6d 65 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 mented by sqlite
366b0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 3_mutex_try().
366c0 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 On those systems
366d0 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f , sqlite3_mutex_
366e0 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c try().** will al
366f0 77 61 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 ways return SQLI
36700 54 45 5f 42 55 53 59 2e 20 20 7b 48 31 37 30 33 TE_BUSY. {H1703
36710 30 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 0} The SQLite co
36720 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 re only ever use
36730 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 s.** sqlite3_mut
36740 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f ex_try() as an o
36750 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 ptimization so t
36760 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c his is acceptabl
36770 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a e behavior..**.*
36780 2a 20 7b 48 31 37 30 33 31 7d 20 54 68 65 20 73 * {H17031} The s
36790 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 qlite3_mutex_lea
367a0 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 ve() routine exi
367b0 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 ts a mutex that
367c0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c was.** previousl
367d0 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 y entered by the
367e0 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 7b same thread. {
367f0 41 31 37 30 33 32 7d 20 54 68 65 20 62 65 68 61 A17032} The beha
36800 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 vior.** is undef
36810 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 ined if the mute
36820 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 x is not current
36830 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 ly entered by th
36840 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 e.** calling thr
36850 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 ead or is not cu
36860 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 rrently allocate
36870 64 2e 20 20 7b 48 31 37 30 33 33 7d 20 53 51 4c d. {H17033} SQL
36880 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 ite will.** neve
36890 72 20 64 6f 20 65 69 74 68 65 72 2e 20 7b 45 4e r do either. {EN
368a0 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 D}.**.** If the
368b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
368c0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 te3_mutex_enter(
368d0 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ), sqlite3_mutex
368e0 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 _try(), or.** sq
368f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
36900 65 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f e() is a NULL po
36910 69 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 inter, then all
36920 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a three routines.*
36930 2a 20 62 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f * behave as no-o
36940 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ps..**.** See al
36950 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 so: [sqlite3_mut
36960 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b ex_held()] and [
36970 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f sqlite3_mutex_no
36980 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c theld()]..*/.SQL
36990 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
369a0 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d mutex *sqlite3_m
369b0 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b utex_alloc(int);
369c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
369d0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 sqlite3_mutex_f
369e0 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ree(sqlite3_mute
369f0 78 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 x*);.SQLITE_API
36a00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 void sqlite3_mut
36a10 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 ex_enter(sqlite3
36a20 5f 6d 75 74 65 78 2a 29 3b 0a 53 51 4c 49 54 45 _mutex*);.SQLITE
36a30 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
36a40 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 _mutex_try(sqlit
36a50 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 53 51 4c 49 e3_mutex*);.SQLI
36a60 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
36a70 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 te3_mutex_leave(
36a80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
36a90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
36aa0 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 : Mutex Methods
36ab0 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30 7d 20 Object {H17120}
36ac0 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 <S20130>.** EXPE
36ad0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 RIMENTAL.**.** A
36ae0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
36af0 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 is structure def
36b00 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 ines the low-lev
36b10 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 el routines.** u
36b20 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 sed to allocate
36b30 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e and use mutexes.
36b40 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 .**.** Usually,
36b50 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
36b60 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e x implementation
36b70 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 s provided by SQ
36b80 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 Lite are.** suff
36b90 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 icient, however
36ba0 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 the user has the
36bb0 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 option of subst
36bc0 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d ituting a custom
36bd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
36be0 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a on for specializ
36bf0 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f ed deployments o
36c00 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 r systems for wh
36c10 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f ich SQLite.** do
36c20 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 es not provide a
36c30 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d suitable implem
36c40 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 entation. In thi
36c50 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 s case, the user
36c60 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 .** creates and
36c70 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 populates an ins
36c80 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 tance of this st
36c90 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a ructure to pass.
36ca0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ** to sqlite3_co
36cb0 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 nfig() along wit
36cc0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f h the [SQLITE_CO
36cd0 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 NFIG_MUTEX] opti
36ce0 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 on..** Additiona
36cf0 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 lly, an instance
36d00 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 of this structu
36d10 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 re can be used a
36d20 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 s an.** output v
36d30 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 ariable when que
36d40 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d rying the system
36d50 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 for the current
36d60 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d mutex.** implem
36d70 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 entation, using
36d80 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
36d90 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 IG_GETMUTEX] opt
36da0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ion..**.** The x
36db0 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 MutexInit method
36dc0 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 defined by this
36dd0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e structure is in
36de0 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 voked as.** part
36df0 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 of system initi
36e00 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 alization by the
36e10 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
36e20 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a ize() function..
36e30 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 65 20 ** {H17001} The
36e40 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 xMutexInit routi
36e50 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c ne shall be call
36e60 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 ed by SQLite onc
36e70 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 e for each.** ef
36e80 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 fective call to
36e90 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
36ea0 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 ize()]..**.** Th
36eb0 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 e xMutexEnd meth
36ec0 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 od defined by th
36ed0 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 is structure is
36ee0 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 invoked as.** pa
36ef0 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 rt of system shu
36f00 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c tdown by the sql
36f10 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
36f20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a function. The.**
36f30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
36f40 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 of this method i
36f50 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 72 65 s expected to re
36f60 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 lease all outsta
36f70 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 nding.** resourc
36f80 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 es obtained by t
36f90 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 he mutex methods
36fa0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c implementation,
36fb0 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 especially.** t
36fc0 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79 hose obtained by
36fd0 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 the xMutexInit
36fe0 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d method. {H17003}
36ff0 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 The xMutexEnd()
37000 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 .** interface sh
37010 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f all be invoked o
37020 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c nce for each cal
37030 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 l to [sqlite3_sh
37040 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a utdown()]..**.**
37050 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 The remaining s
37060 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 even methods def
37070 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 ined by this str
37080 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 41 6c ucture (xMutexAl
37090 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 loc,.** xMutexFr
370a0 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 2c ee, xMutexEnter,
370b0 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 74 xMutexTry, xMut
370c0 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 48 exLeave, xMutexH
370d0 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 eld and.** xMute
370e0 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d xNotheld) implem
370f0 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ent the followin
37100 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 72 65 g interfaces (re
37110 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a spectively):.**.
37120 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 ** <ul>.** <li
37130 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
37140 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e x_alloc()] </li>
37150 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
37160 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 ite3_mutex_free(
37170 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
37180 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
37190 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 ex_enter()] </li
371a0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
371b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
371c0 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
371d0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
371e0 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 ex_leave()] </li
371f0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
37200 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 lite3_mutex_held
37210 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
37220 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
37230 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c tex_notheld()] <
37240 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a /li>.** </ul>.**
37250 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 .** The only dif
37260 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 ference is that
37270 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 the public sqlit
37280 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 e3_XXX functions
37290 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 enumerated.** a
372a0 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 bove silently ig
372b0 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 nore any invocat
372c0 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 ions that pass a
372d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e NULL pointer in
372e0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 stead.** of a va
372f0 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 lid mutex handle
37300 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 . The implementa
37310 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 tions of the met
37320 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 hods defined.**
37330 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 by this structur
37340 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 e are not requir
37350 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 ed to handle thi
37360 73 20 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 s case, the resu
37370 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e lts.** of passin
37380 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 g a NULL pointer
37390 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 instead of a va
373a0 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 lid mutex handle
373b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a are undefined.*
373c0 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 * (i.e. it is ac
373d0 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 ceptable to prov
373e0 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 ide an implement
373f0 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 ation that segfa
37400 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 ults if.** it is
37410 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 passed a NULL p
37420 6f 69 6e 74 65 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 ointer)..**.** T
37430 68 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 he xMutexInit()
37440 6d 65 74 68 6f 64 20 6d 75 73 74 20 62 65 20 74 method must be t
37450 68 72 65 61 64 73 61 66 65 2e 20 20 49 74 20 6d hreadsafe. It m
37460 75 73 74 20 62 65 20 68 61 72 6d 6c 65 73 73 20 ust be harmless
37470 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 78 4d 75 to.** invoke xMu
37480 74 65 78 49 6e 69 74 28 29 20 6d 75 74 69 70 6c texInit() mutipl
37490 65 20 74 69 6d 65 73 20 77 69 74 68 69 6e 20 74 e times within t
374a0 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 20 he same process
374b0 61 6e 64 20 77 69 74 68 6f 75 74 0a 2a 2a 20 69 and without.** i
374c0 6e 74 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c 73 ntervening calls
374d0 20 74 6f 20 78 4d 75 74 65 78 45 6e 64 28 29 2e to xMutexEnd().
374e0 20 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 Second and sub
374f0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
37500 0a 2a 2a 20 78 4d 75 74 65 78 49 6e 69 74 28 29 .** xMutexInit()
37510 20 6d 75 73 74 20 62 65 20 6e 6f 2d 6f 70 73 2e must be no-ops.
37520 0a 2a 2a 0a 2a 2a 20 78 4d 75 74 65 78 49 6e 69 .**.** xMutexIni
37530 74 28 29 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 t() must not use
37540 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 SQLite memory a
37550 6c 6c 6f 63 61 74 69 6f 6e 20 28 5b 73 71 6c 69 llocation ([sqli
37560 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a te3_malloc()].**
37570 20 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61 and its associa
37580 74 65 73 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 tes). Similarly
37590 2c 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 , xMutexAlloc()
375a0 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c must not use SQL
375b0 69 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ite memory.** al
375c0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 73 location for a s
375d0 74 61 74 69 63 20 6d 75 74 65 78 2e 20 20 48 6f tatic mutex. Ho
375e0 77 65 76 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f wever xMutexAllo
375f0 63 28 29 20 6d 61 79 20 75 73 65 20 53 51 4c 69 c() may use SQLi
37600 74 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c te.** memory all
37610 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 ocation for a fa
37620 73 74 20 6f 72 20 72 65 63 75 72 73 69 76 65 20 st or recursive
37630 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c mutex..**.** SQL
37640 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 ite will invoke
37650 74 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20 the xMutexEnd()
37660 6d 65 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c method when [sql
37670 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
37680 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 is.** called, b
37690 75 74 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 ut only if the p
376a0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 rior call to xMu
376b0 74 65 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64 texInit returned
376c0 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 SQLITE_OK..** I
376d0 66 20 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69 f xMutexInit fai
376e0 6c 73 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 ls in any way, i
376f0 74 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f t is expected to
37700 20 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20 clean up after
37710 69 74 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 itself.** prior
37720 74 6f 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f to returning..*/
37730 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
37740 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
37750 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 thods sqlite3_mu
37760 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 tex_methods;.str
37770 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 uct sqlite3_mute
37780 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e x_methods {. in
37790 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 t (*xMutexInit)(
377a0 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 void);. int (*x
377b0 4d 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b MutexEnd)(void);
377c0 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 . sqlite3_mutex
377d0 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 *(*xMutexAlloc)
377e0 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a (int);. void (*
377f0 78 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 xMutexFree)(sqli
37800 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 te3_mutex *);.
37810 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 void (*xMutexEnt
37820 65 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 er)(sqlite3_mute
37830 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d x *);. int (*xM
37840 75 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 utexTry)(sqlite3
37850 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 _mutex *);. voi
37860 64 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 d (*xMutexLeave)
37870 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
37880 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 );. int (*xMute
37890 78 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d xHeld)(sqlite3_m
378a0 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 utex *);. int (
378b0 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 *xMutexNotheld)(
378c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 sqlite3_mutex *)
378d0 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ;.};../*.** CAPI
378e0 33 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 3REF: Mutex Veri
378f0 66 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 fication Routine
37900 73 20 7b 48 31 37 30 38 30 7d 20 3c 53 32 30 31 s {H17080} <S201
37910 33 30 3e 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 30> <S30800>.**.
37920 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d ** The sqlite3_m
37930 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 utex_held() and
37940 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f sqlite3_mutex_no
37950 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 theld() routines
37960 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 .** are intended
37970 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 for use inside
37980 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 assert() stateme
37990 6e 74 73 2e 20 7b 48 31 37 30 38 31 7d 20 54 68 nts. {H17081} Th
379a0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a e SQLite core.**
379b0 20 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 73 never uses thes
379c0 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70 e routines excep
379d0 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65 t inside an asse
379e0 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61 rt() and applica
379f0 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 tions.** are adv
37a00 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 ised to follow t
37a10 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63 he lead of the c
37a20 6f 72 65 2e 20 20 7b 48 31 37 30 38 32 7d 20 54 ore. {H17082} T
37a30 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 he core only.**
37a40 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 provides impleme
37a50 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 ntations for the
37a60 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e se routines when
37a70 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a it is compiled.
37a80 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 ** with the SQLI
37a90 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20 TE_DEBUG flag.
37aa0 7b 41 31 37 30 38 37 7d 20 45 78 74 65 72 6e 61 {A17087} Externa
37ab0 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e l mutex implemen
37ac0 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f tations.** are o
37ad0 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 nly required to
37ae0 70 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f provide these ro
37af0 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 utines if SQLITE
37b00 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 _DEBUG is.** def
37b10 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 ined and if NDEB
37b20 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 UG is not define
37b30 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 d..**.** {H17083
37b40 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 } These routines
37b50 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 should return t
37b60 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78 rue if the mutex
37b70 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65 in their argume
37b80 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 nt.** is held or
37b90 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65 not held, respe
37ba0 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20 ctively, by the
37bb0 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a calling thread..
37bc0 2a 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 **.** {X17084} T
37bd0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
37be0 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 n is not require
37bf0 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 d to provided ve
37c00 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a rsions of these.
37c10 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 ** routines that
37c20 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 actually work.
37c30 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 If the implement
37c40 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 ation does not p
37c50 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a rovide working.*
37c60 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 * versions of th
37c70 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 ese routines, it
37c80 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 should at least
37c90 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 20 74 provide stubs t
37ca0 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 hat always.** re
37cb0 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 turn true so tha
37cc0 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 t one does not g
37cd0 65 74 20 73 70 75 72 69 6f 75 73 20 61 73 73 65 et spurious asse
37ce0 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a rtion failures..
37cf0 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49 **.** {H17085} I
37d00 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 f the argument t
37d10 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f o sqlite3_mutex_
37d20 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c held() is a NULL
37d30 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a pointer then.**
37d40 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f the routine sho
37d50 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 7b uld return 1. {
37d60 45 4e 44 7d 20 54 68 69 73 20 73 65 65 6d 73 20 END} This seems
37d70 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 counter-intuitiv
37d80 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 e since.** clear
37d90 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e ly the mutex can
37da0 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20 69 not be held if i
37db0 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 t does not exist
37dc0 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 . But the.** th
37dd0 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 e reason the mut
37de0 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 ex does not exis
37df0 74 20 69 73 20 62 65 63 61 75 73 65 20 74 68 65 t is because the
37e00 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a build is not.**
37e10 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 using mutexes.
37e20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 And we do not w
37e30 61 6e 74 20 74 68 65 20 61 73 73 65 72 74 28 29 ant the assert()
37e40 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a containing the.
37e50 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ** call to sqlit
37e60 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 e3_mutex_held()
37e70 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f to fail, so a no
37e80 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73 n-zero return is
37e90 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69 .** the appropri
37ea0 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e ate thing to do.
37eb0 20 20 7b 48 31 37 30 38 36 7d 20 54 68 65 20 73 {H17086} The s
37ec0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
37ed0 68 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 held().** interf
37ee0 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 ace should also
37ef0 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 return 1 when gi
37f00 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ven a NULL point
37f10 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 er..*/.SQLITE_AP
37f20 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 I int sqlite3_mu
37f30 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 tex_held(sqlite3
37f40 5f 6d 75 74 65 78 2a 29 3b 0a 53 51 4c 49 54 45 _mutex*);.SQLITE
37f50 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
37f60 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 _mutex_notheld(s
37f70 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a qlite3_mutex*);.
37f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
37f90 20 4d 75 74 65 78 20 54 79 70 65 73 20 7b 48 31 Mutex Types {H1
37fa0 37 30 30 31 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 7001} <H17000>.*
37fb0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
37fc0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 3_mutex_alloc()]
37fd0 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 interface takes
37fe0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
37ff0 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f nt.** which is o
38000 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
38010 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a ger constants..*
38020 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f 66 20 *.** The set of
38030 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 6d static mutexes m
38040 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f ay change from o
38050 6e 65 20 53 51 4c 69 74 65 20 72 65 6c 65 61 73 ne SQLite releas
38060 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 e to the.** next
38070 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
38080 74 68 61 74 20 6f 76 65 72 72 69 64 65 20 74 68 that override th
38090 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74 65 78 e built-in mutex
380a0 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 65 0a 2a logic must be.*
380b0 2a 20 70 72 65 70 61 72 65 64 20 74 6f 20 61 63 * prepared to ac
380c0 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69 74 69 commodate additi
380d0 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 onal static mute
380e0 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 xes..*/.#define
380f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
38100 54 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a T 0.
38110 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
38120 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20 UTEX_RECURSIVE
38130 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
38140 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
38150 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a TIC_MASTER 2.
38160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
38170 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 UTEX_STATIC_MEM
38180 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 3 /* sqli
38190 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a te3_malloc() */.
381a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
381b0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 UTEX_STATIC_MEM2
381c0 20 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f 54 20 4 /* NOT
381d0 55 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e 65 20 USED */.#define
381e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
381f0 54 49 43 5f 4f 50 45 4e 20 20 20 20 20 20 34 20 TIC_OPEN 4
38200 20 2f 2a 20 73 71 6c 69 74 65 33 42 74 72 65 65 /* sqlite3Btree
38210 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66 69 6e Open() */.#defin
38220 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 e SQLITE_MUTEX_S
38230 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 TATIC_PRNG
38240 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 5 /* sqlite3_ra
38250 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e ndom() */.#defin
38260 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 e SQLITE_MUTEX_S
38270 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20 20 TATIC_LRU
38280 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 6 /* lru page l
38290 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ist */.#define S
382a0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
382b0 49 43 5f 4c 52 55 32 20 20 20 20 20 20 37 20 20 IC_LRU2 7
382c0 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 /* lru page list
382d0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
382e0 52 45 46 3a 20 52 65 74 72 69 65 76 65 20 74 68 REF: Retrieve th
382f0 65 20 6d 75 74 65 78 20 66 6f 72 20 61 20 64 61 e mutex for a da
38300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
38310 6e 20 7b 48 31 37 30 30 32 7d 20 3c 48 31 37 30 n {H17002} <H170
38320 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 00>.**.** This i
38330 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
38340 20 61 20 70 6f 69 6e 74 65 72 20 74 68 65 20 5b a pointer the [
38350 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f sqlite3_mutex] o
38360 62 6a 65 63 74 20 74 68 61 74 20 0a 2a 2a 20 73 bject that .** s
38370 65 72 69 61 6c 69 7a 65 73 20 61 63 63 65 73 73 erializes access
38380 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 to the [databas
38390 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 67 69 e connection] gi
383a0 76 65 6e 20 69 6e 20 74 68 65 20 61 72 67 75 6d ven in the argum
383b0 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 ent.** when the
383c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
383d0 20 69 73 20 53 65 72 69 61 6c 69 7a 65 64 2e 0a is Serialized..
383e0 2a 2a 20 49 66 20 74 68 65 20 5b 74 68 72 65 61 ** If the [threa
383f0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 69 ding mode] is Si
38400 6e 67 6c 65 2d 74 68 72 65 61 64 20 6f 72 20 4d ngle-thread or M
38410 75 6c 74 69 2d 74 68 72 65 61 64 20 74 68 65 6e ulti-thread then
38420 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
38430 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
38440 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 pointer..*/.SQLI
38450 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 6d TE_API sqlite3_m
38460 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62 utex *sqlite3_db
38470 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29 _mutex(sqlite3*)
38480 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
38490 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e F: Low-Level Con
384a0 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65 trol Of Database
384b0 20 46 69 6c 65 73 20 7b 48 31 31 33 30 30 7d 20 Files {H11300}
384c0 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b <S30800>.**.** {
384d0 48 31 31 33 30 31 7d 20 54 68 65 20 5b 73 71 6c H11301} The [sql
384e0 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
384f0 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d l()] interface m
38500 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61 akes a direct ca
38510 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 ll to the.** xFi
38520 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
38530 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
38540 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
38550 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a ject associated.
38560 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ** with a partic
38570 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64 ular database id
38580 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
38590 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
385a0 20 7b 48 31 31 33 30 32 7d 20 54 68 65 0a 2a 2a {H11302} The.**
385b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
385c0 61 62 61 73 65 20 69 73 20 74 68 65 20 6e 61 6d abase is the nam
385d0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68 e assigned to th
385e0 65 20 64 61 74 61 62 61 73 65 20 62 79 20 74 68 e database by th
385f0 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61 e.** <a href="la
38600 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e ng_attach.html">
38610 41 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63 ATTACH</a> SQL c
38620 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 65 6e ommand that open
38630 65 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 ed the.** databa
38640 73 65 2e 20 7b 48 31 31 33 30 33 7d 20 54 6f 20 se. {H11303} To
38650 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e control the main
38660 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
38670 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 use the name "ma
38680 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c in".** or a NULL
38690 20 70 6f 69 6e 74 65 72 2e 20 7b 48 31 31 33 30 pointer. {H1130
386a0 34 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 4} The third and
386b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
386c0 72 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 rs to this routi
386d0 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 ne.** are passed
386e0 20 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 directly throug
386f0 68 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 h to the second
38700 61 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 and third parame
38710 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 ters of.** the x
38720 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
38730 6f 64 2e 20 20 7b 48 31 31 33 30 35 7d 20 54 68 od. {H11305} Th
38740 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
38750 66 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 f the xFileContr
38760 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 ol.** method bec
38770 6f 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 omes the return
38780 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f value of this ro
38790 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 utine..**.** {H1
387a0 31 33 30 36 7d 20 49 66 20 74 68 65 20 73 65 63 1306} If the sec
387b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a ond parameter (z
387c0 44 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 DbName) does not
387d0 20 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 match the name
387e0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 of any.** open d
387f0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 atabase file, th
38800 65 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 en SQLITE_ERROR
38810 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 48 31 is returned. {H1
38820 31 33 30 37 7d 20 54 68 69 73 20 65 72 72 6f 72 1307} This error
38830 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 .** code is not
38840 72 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 remembered and w
38850 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c ill not be recal
38860 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f led by [sqlite3_
38870 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 errcode()].** or
38880 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
38890 28 29 5d 2e 20 7b 41 31 31 33 30 38 7d 20 54 68 ()]. {A11308} Th
388a0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 e underlying xFi
388b0 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
388c0 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 might.** also r
388d0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 eturn SQLITE_ERR
388e0 4f 52 2e 20 20 7b 41 31 31 33 30 39 7d 20 54 68 OR. {A11309} Th
388f0 65 72 65 20 69 73 20 6e 6f 20 77 61 79 20 74 6f ere is no way to
38900 20 64 69 73 74 69 6e 67 75 69 73 68 20 62 65 74 distinguish bet
38910 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 ween.** an incor
38920 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 rect zDbName and
38930 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 an SQLITE_ERROR
38940 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 return from the
38950 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 underlying.** x
38960 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
38970 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 od. {END}.**.**
38980 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 See also: [SQLIT
38990 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
389a0 45 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 E].*/.SQLITE_API
389b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c int sqlite3_fil
389c0 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 e_control(sqlite
389d0 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 3*, const char *
389e0 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c zDbName, int op,
389f0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
38a00 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e CAPI3REF: Testin
38a10 67 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31 g Interface {H11
38a20 34 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 400} <S30800>.**
38a30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
38a40 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 test_control() i
38a50 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
38a60 20 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74 to read out int
38a70 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f ernal.** state o
38a80 66 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 f SQLite and to
38a90 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e inject faults in
38aa0 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65 to SQLite for te
38ab0 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 sting.** purpose
38ac0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 s. The first pa
38ad0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 rameter is an op
38ae0 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 eration code tha
38af0 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 t determines.**
38b00 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e the number, mean
38b10 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 ing, and operati
38b20 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 on of all subseq
38b30 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e uent parameters.
38b40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
38b50 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 rface is not for
38b60 20 75 73 65 20 62 79 20 61 70 70 6c 69 63 61 74 use by applicat
38b70 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73 ions. It exists
38b80 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 solely.** for v
38b90 65 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72 erifying the cor
38ba0 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f rect operation o
38bb0 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 f the SQLite lib
38bc0 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 rary. Depending
38bd0 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 .** on how the S
38be0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 QLite library is
38bf0 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 compiled, this
38c00 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 interface might
38c10 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a not exist..**.**
38c20 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 The details of
38c30 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f the operation co
38c40 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 des, their meani
38c50 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74 ngs, the paramet
38c60 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 ers.** they take
38c70 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65 79 20 , and what they
38c80 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 do are all subje
38c90 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 ct to change wit
38ca0 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 hout notice..**
38cb0 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 Unlike most of t
38cc0 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74 he SQLite API, t
38cd0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
38ce0 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 not guaranteed t
38cf0 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e o.** operate con
38d00 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f sistently from o
38d10 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 ne release to th
38d20 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 e next..*/.SQLIT
38d30 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
38d40 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 69 3_test_control(i
38d50 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a nt op, ...);../*
38d60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 .** CAPI3REF: Te
38d70 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 20 sting Interface
38d80 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 65 73 20 Operation Codes
38d90 7b 48 31 31 34 31 30 7d 20 3c 48 31 31 34 30 30 {H11410} <H11400
38da0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f >.**.** These co
38db0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
38dc0 76 61 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e 20 valid operation
38dd0 63 6f 64 65 20 70 61 72 61 6d 65 74 65 72 73 20 code parameters
38de0 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 20 66 used.** as the f
38df0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
38e00 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 [sqlite3_test_c
38e10 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a ontrol()]..**.**
38e20 20 54 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 These parameter
38e30 73 20 61 6e 64 20 74 68 65 69 72 20 6d 65 61 6e s and their mean
38e40 69 6e 67 73 20 61 72 65 20 73 75 62 6a 65 63 74 ings are subject
38e50 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77 69 to change.** wi
38e60 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20 54 thout notice. T
38e70 68 65 73 65 20 76 61 6c 75 65 73 20 61 72 65 20 hese values are
38e80 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72 70 for testing purp
38e90 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 70 oses only..** Ap
38ea0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
38eb0 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f 66 d not use any of
38ec0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 these parameter
38ed0 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c s or the.** [sql
38ee0 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f ite3_test_contro
38ef0 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a l()] interface..
38f00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
38f10 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f E_TESTCTRL_PRNG_
38f20 53 41 56 45 20 20 20 20 20 20 20 20 20 20 20 20 SAVE
38f30 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 5.#define SQ
38f40 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 LITE_TESTCTRL_PR
38f50 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 20 20 20 NG_RESTORE
38f60 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
38f70 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
38f80 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 20 20 20 _PRNG_RESET
38f90 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 7.#def
38fa0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
38fb0 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 53 54 20 TRL_BITVEC_TEST
38fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 8.#
38fd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
38fe0 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f 49 4e 53 STCTRL_FAULT_INS
38ff0 54 41 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 TALL
39000 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 9.#define SQLITE
39010 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e 49 47 4e _TESTCTRL_BENIGN
39020 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20 20 _MALLOC_HOOKS
39030 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 10.#define SQL
39040 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 45 4e ITE_TESTCTRL_PEN
39050 44 49 4e 47 5f 42 59 54 45 20 20 20 20 20 20 20 DING_BYTE
39060 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 11.#define
39070 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
39080 41 53 53 45 52 54 20 20 20 20 20 20 20 20 20 20 ASSERT
39090 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 12.#defi
390a0 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
390b0 52 4c 5f 41 4c 57 41 59 53 20 20 20 20 20 20 20 RL_ALWAYS
390c0 20 20 20 20 20 20 20 20 20 20 20 31 33 0a 23 64 13.#d
390d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
390e0 54 43 54 52 4c 5f 52 45 53 45 52 56 45 20 20 20 TCTRL_RESERVE
390f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 14
39100 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
39110 3a 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 : SQLite Runtime
39120 20 53 74 61 74 75 73 20 7b 48 31 37 32 30 30 7d Status {H17200}
39130 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 <S60200>.** EXP
39140 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
39150 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 This interface i
39160 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 s used to retrie
39170 76 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 ve runtime statu
39180 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a s information.**
39190 20 61 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f about the prefo
391a0 72 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 rmance of SQLite
391b0 2c 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 , and optionally
391c0 20 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 to reset variou
391d0 73 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d s.** highwater m
391e0 61 72 6b 73 2e 20 20 54 68 65 20 66 69 72 73 74 arks. The first
391f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 argument is an
39200 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 integer code for
39210 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 .** the specific
39220 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 parameter to me
39230 61 73 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a asure. Recogniz
39240 65 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 ed integer codes
39250 0a 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20 66 .** are of the f
39260 6f 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 orm [SQLITE_STAT
39270 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c US_MEMORY_USED |
39280 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e SQLITE_STATUS_.
39290 2e 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 ..]..** The curr
392a0 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 ent value of the
392b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 parameter is re
392c0 74 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 turned into *pCu
392d0 72 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 rrent..** The hi
392e0 67 68 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 ghest recorded v
392f0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 alue is returned
39300 20 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e in *pHighwater.
39310 20 20 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 If the.** rese
39320 74 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 tFlag is true, t
39330 68 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 hen the highest
39340 72 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 record value is
39350 72 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a reset after.** *
39360 70 48 69 67 68 77 61 74 65 72 20 69 73 20 77 72 pHighwater is wr
39370 69 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 itten. Some para
39380 6d 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 meters do not re
39390 63 6f 72 64 20 74 68 65 20 68 69 67 68 65 73 74 cord the highest
393a0 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 .** value. For
393b0 74 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 those parameters
393c0 0a 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 .** nothing is w
393d0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 ritten into *pHi
393e0 67 68 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 ghwater and the
393f0 72 65 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e resetFlag is ign
39400 6f 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 ored..** Other p
39410 61 72 61 6d 65 74 65 72 73 20 72 65 63 6f 72 64 arameters record
39420 20 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 77 61 only the highwa
39430 74 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 ter mark and not
39440 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
39450 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 73 value. For thes
39460 65 20 6c 61 74 74 65 72 20 70 61 72 61 6d 65 74 e latter paramet
39470 65 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 ers nothing is w
39480 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 ritten into *pCu
39490 72 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 rrent..**.** Thi
394a0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
394b0 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 s SQLITE_OK on s
394c0 75 63 63 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e uccess and a non
394d0 2d 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 -zero.** [error
394e0 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 code] on failure
394f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
39500 74 69 6e 65 20 69 73 20 74 68 72 65 61 64 73 61 tine is threadsa
39510 66 65 20 62 75 74 20 69 73 20 6e 6f 74 20 61 74 fe but is not at
39520 6f 6d 69 63 2e 20 20 54 68 69 73 20 72 6f 75 74 omic. This rout
39530 69 6e 65 20 63 61 6e 20 62 65 0a 2a 2a 20 63 61 ine can be.** ca
39540 6c 6c 65 64 20 77 68 69 6c 65 20 6f 74 68 65 72 lled while other
39550 20 74 68 72 65 61 64 73 20 61 72 65 20 72 75 6e threads are run
39560 6e 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6f 72 ning the same or
39570 20 64 69 66 66 65 72 65 6e 74 20 53 51 4c 69 74 different SQLit
39580 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e e.** interfaces.
39590 20 20 48 6f 77 65 76 65 72 20 74 68 65 20 76 61 However the va
395a0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 69 6e lues returned in
395b0 20 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 0a 2a *pCurrent and.*
395c0 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 72 65 * *pHighwater re
395d0 66 6c 65 63 74 20 74 68 65 20 73 74 61 74 75 73 flect the status
395e0 20 6f 66 20 53 51 4c 69 74 65 20 61 74 20 64 69 of SQLite at di
395f0 66 66 65 72 65 6e 74 20 70 6f 69 6e 74 73 20 69 fferent points i
39600 6e 20 74 69 6d 65 0a 2a 2a 20 61 6e 64 20 69 74 n time.** and it
39610 20 69 73 20 70 6f 73 73 69 62 6c 65 20 74 68 61 is possible tha
39620 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 t another thread
39630 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 might change th
39640 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 e parameter.** i
39650 6e 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 69 n between the ti
39660 6d 65 73 20 77 68 65 6e 20 2a 70 43 75 72 72 65 mes when *pCurre
39670 6e 74 20 61 6e 64 20 2a 70 48 69 67 68 77 61 74 nt and *pHighwat
39680 65 72 20 61 72 65 20 77 72 69 74 74 65 6e 2e 0a er are written..
39690 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
396a0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 [sqlite3_db_stat
396b0 75 73 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f us()].*/.SQLITE_
396c0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 API SQLITE_EXPER
396d0 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 IMENTAL int sqli
396e0 74 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f te3_status(int o
396f0 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74 p, int *pCurrent
39700 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65 , int *pHighwate
39710 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67 r, int resetFlag
39720 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 );.../*.** CAPI3
39730 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 REF: Status Para
39740 6d 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d 20 meters {H17250}
39750 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45 <H17200>.** EXPE
39760 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
39770 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e hese integer con
39780 73 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 65 stants designate
39790 20 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d various run-tim
397a0 65 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 e status paramet
397b0 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 ers.** that can
397c0 62 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b be returned by [
397d0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 sqlite3_status()
397e0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a ]..**.** <dl>.**
397f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 <dt>SQLITE_STAT
39800 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f US_MEMORY_USED</
39810 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
39820 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
39830 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20 current amount
39840 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65 of memory checke
39850 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b d out.** using [
39860 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
39870 5d 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 74 ], either direct
39880 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c 79 ly or indirectly
39890 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 65 . The.** figure
398a0 20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 20 includes calls
398b0 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 33 made to [sqlite3
398c0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68 _malloc()] by th
398d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
398e0 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65 and internal me
398f0 6d 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 68 mory usage by th
39900 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
39910 2e 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f 72 . Scratch memor
39920 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 y.** controlled
39930 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
39940 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 61 G_SCRATCH] and a
39950 75 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 61 uxiliary page-ca
39960 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f che.** memory co
39970 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c ntrolled by [SQL
39980 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
39990 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63 ACHE] is not inc
399a0 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73 luded in.** this
399b0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 parameter. The
399c0 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 amount returned
399d0 20 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 74 is the sum of t
399e0 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a he allocation.**
399f0 20 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 74 sizes as report
39a00 65 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 20 ed by the xSize
39a10 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74 method in [sqlit
39a20 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e e3_mem_methods].
39a30 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
39a40 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 SQLITE_STATUS_MA
39a50 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a LLOC_SIZE</dt>.*
39a60 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
39a70 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 eter records the
39a80 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 largest memory
39a90 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 allocation reque
39aa0 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 st.** handed to
39ab0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
39ac0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
39ad0 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68 ealloc()] (or th
39ae0 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 eir.** internal
39af0 65 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f equivalents). O
39b00 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 nly the value re
39b10 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a turned in the.**
39b20 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 *pHighwater par
39b30 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
39b40 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 e3_status()] is
39b50 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a of interest. .*
39b60 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 * The value writ
39b70 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 ten into the *pC
39b80 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 urrent parameter
39b90 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f is undefined.</
39ba0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
39bb0 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 LITE_STATUS_PAGE
39bc0 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e 0a CACHE_USED</dt>.
39bd0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 ** <dd>This para
39be0 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 meter returns th
39bf0 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
39c00 73 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68 s used out of th
39c10 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 20 e.** [pagecache
39c20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
39c30 5d 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66 69 ] that was confi
39c40 67 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a 20 gured using .**
39c50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
39c60 41 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65 0a AGECACHE]. The.
39c70 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 ** value returne
39c80 64 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20 6e d is in pages, n
39c90 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 ot in bytes.</dd
39ca0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
39cb0 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 TE_STATUS_PAGECA
39cc0 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 CHE_OVERFLOW</dt
39cd0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
39ce0 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 rameter returns
39cf0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
39d00 74 65 73 20 6f 66 20 70 61 67 65 20 63 61 63 68 tes of page cach
39d10 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e.** allocation
39d20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 which could not
39d30 62 65 20 73 74 61 74 69 73 66 69 65 64 20 62 79 be statisfied by
39d40 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
39d50 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a 2a FIG_PAGECACHE].*
39d60 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 65 * buffer and whe
39d70 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65 re forced to ove
39d80 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65 rflow to [sqlite
39d90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 3_malloc()]. Th
39da0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 61 e.** returned va
39db0 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c lue includes all
39dc0 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 ocations that ov
39dd0 65 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 erflowed because
39de0 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 74 they.** where t
39df0 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20 77 oo large (they w
39e00 65 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 ere larger than
39e10 74 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65 74 the "sz" paramet
39e20 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 er to.** [SQLITE
39e30 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
39e40 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 69 E]) and allocati
39e50 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f ons that overflo
39e60 77 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 6e wed because.** n
39e70 6f 20 73 70 61 63 65 20 77 61 73 20 6c 65 66 74 o space was left
39e80 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 in the page cac
39e90 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c he.</dd>.**.** <
39ea0 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
39eb0 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 3c _PAGECACHE_SIZE<
39ec0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
39ed0 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 parameter recor
39ee0 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d ds the largest m
39ef0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
39f00 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 request.** hand
39f10 65 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68 65 ed to [pagecache
39f20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
39f30 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 r]. Only the va
39f40 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 lue returned in
39f50 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 the.** *pHighwat
39f60 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 er parameter to
39f70 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
39f80 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 )] is of interes
39f90 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 t. .** The valu
39fa0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 e written into t
39fb0 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 he *pCurrent par
39fc0 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 ameter is undefi
39fd0 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ned.</dd>.**.**
39fe0 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 <dt>SQLITE_STATU
39ff0 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c 2f S_SCRATCH_USED</
3a000 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
3a010 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e parameter return
3a020 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
3a030 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 64 allocations used
3a040 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b out of the.** [
3a050 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 scratch memory a
3a060 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 llocator] config
3a070 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 ured using.** [S
3a080 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
3a090 41 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c 75 ATCH]. The valu
3a0a0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e e returned is in
3a0b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f allocations, no
3a0c0 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 20 t.** in bytes.
3a0d0 53 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 74 Since a single t
3a0e0 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 68 hread may only h
3a0f0 61 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68 20 ave one scratch
3a100 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75 allocation.** ou
3a110 74 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69 6d tstanding at tim
3a120 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 e, this paramete
3a130 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 74 r also reports t
3a140 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 he number of thr
3a150 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 63 eads.** using sc
3a160 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 20 ratch memory at
3a170 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f the same time.</
3a180 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
3a190 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 LITE_STATUS_SCRA
3a1a0 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 TCH_OVERFLOW</dt
3a1b0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
3a1c0 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 rameter returns
3a1d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
3a1e0 74 65 73 20 6f 66 20 73 63 72 61 74 63 68 20 6d tes of scratch m
3a1f0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
3a200 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 ion which could
3a210 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65 not be statisfie
3a220 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 d by the [SQLITE
3a230 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
3a240 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 .** buffer and w
3a250 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f here forced to o
3a260 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 verflow to [sqli
3a270 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 te3_malloc()].
3a280 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 65 The values.** re
3a290 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 6f turned include o
3a2a0 76 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73 65 verflows because
3a2b0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61 the requested a
3a2c0 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 6f llocation was to
3a2d0 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 61 o.** larger (tha
3a2e0 74 20 69 73 2c 20 62 65 63 61 75 73 65 20 74 68 t is, because th
3a2f0 65 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f e requested allo
3a300 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 65 cation was large
3a310 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 73 r than the.** "s
3a320 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 z" parameter to
3a330 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
3a340 43 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65 63 CRATCH]) and bec
3a350 61 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68 20 ause no scratch
3a360 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 20 buffer.** slots
3a370 77 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a were available..
3a380 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ** </dd>.**.** <
3a390 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
3a3a0 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f 64 _SCRATCH_SIZE</d
3a3b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
3a3c0 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 arameter records
3a3d0 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d the largest mem
3a3e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
3a3f0 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 equest.** handed
3a400 20 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 6d to [scratch mem
3a410 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 ory allocator].
3a420 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 Only the value
3a430 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a returned in the.
3a440 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 ** *pHighwater p
3a450 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
3a460 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 ite3_status()] i
3a470 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 s of interest.
3a480 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 .** The value wr
3a490 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a itten into the *
3a4a0 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 pCurrent paramet
3a4b0 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e er is undefined.
3a4c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
3a4d0 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 SQLITE_STATUS_PA
3a4e0 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a RSER_STACK</dt>.
3a4f0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 ** <dd>This para
3a500 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 meter records th
3a510 65 20 64 65 65 70 65 73 74 20 70 61 72 73 65 72 e deepest parser
3a520 20 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20 6f stack. It is o
3a530 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 75 nly.** meaningfu
3a540 6c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 l if SQLite is c
3a550 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59 59 ompiled with [YY
3a560 54 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 50 TRACKMAXSTACKDEP
3a570 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 TH].</dd>.** </d
3a580 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 61 l>.**.** New sta
3a590 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 20 6d tus parameters m
3a5a0 61 79 20 62 65 20 61 64 64 65 64 20 66 72 6f 6d ay be added from
3a5b0 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a 2a time to time..*
3a5c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3a5d0 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 _STATUS_MEMORY_U
3a5e0 53 45 44 20 20 20 20 20 20 20 20 20 20 30 0a 23 SED 0.#
3a5f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
3a600 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55 ATUS_PAGECACHE_U
3a610 53 45 44 20 20 20 20 20 20 20 31 0a 23 64 65 66 SED 1.#def
3a620 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
3a630 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52 S_PAGECACHE_OVER
3a640 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e 65 FLOW 2.#define
3a650 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 SQLITE_STATUS_S
3a660 43 52 41 54 43 48 5f 55 53 45 44 20 20 20 20 20 CRATCH_USED
3a670 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
3a680 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 LITE_STATUS_SCRA
3a690 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 20 TCH_OVERFLOW
3a6a0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
3a6b0 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f E_STATUS_MALLOC_
3a6c0 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 35 0a SIZE 5.
3a6d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
3a6e0 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41 TATUS_PARSER_STA
3a6f0 43 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 CK 6.#de
3a700 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
3a710 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a US_PAGECACHE_SIZ
3a720 45 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e E 7.#defin
3a730 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f e SQLITE_STATUS_
3a740 53 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20 20 SCRATCH_SIZE
3a750 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 8../*.** CA
3a760 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
3a770 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 74 Connection Stat
3a780 75 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 30 us {H17500} <S60
3a790 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 200>.** EXPERIME
3a7a0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 NTAL.**.** This
3a7b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
3a7c0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 d to retrieve ru
3a7d0 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 ntime status inf
3a7e0 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f ormation .** abo
3a7f0 75 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 74 ut a single [dat
3a800 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a810 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 ]. The first ar
3a820 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
3a830 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3a840 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 62 tion object to b
3a850 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 e interrogated.
3a860 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
3a870 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 70 ment.** is the p
3a880 61 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 65 arameter to inte
3a890 72 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65 6e rrogate. Curren
3a8a0 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 6c tly, the only al
3a8b0 6c 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20 66 lowed value.** f
3a8c0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 or the second pa
3a8d0 72 61 6d 65 74 65 72 20 69 73 20 5b 53 51 4c 49 rameter is [SQLI
3a8e0 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b TE_DBSTATUS_LOOK
3a8f0 41 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20 ASIDE_USED]..**
3a900 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6f Additional optio
3a910 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 61 ns will likely a
3a920 70 70 65 61 72 20 69 6e 20 66 75 74 75 72 65 20 ppear in future
3a930 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
3a940 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 75 te..**.** The cu
3a950 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 rrent value of t
3a960 68 65 20 72 65 71 75 65 73 74 65 64 20 70 61 72 he requested par
3a970 61 6d 65 74 65 72 20 69 73 20 77 72 69 74 74 65 ameter is writte
3a980 6e 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a 20 n into *pCur.**
3a990 61 6e 64 20 74 68 65 20 68 69 67 68 65 73 74 20 and the highest
3a9a0 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 instantaneous va
3a9b0 6c 75 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 lue is written i
3a9c0 6e 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 49 66 nto *pHiwtr. If
3a9d0 0a 2a 2a 20 74 68 65 20 72 65 73 65 74 46 6c 67 .** the resetFlg
3a9e0 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 is true, then t
3a9f0 68 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 he highest insta
3aa00 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 ntaneous value i
3aa10 73 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 6b 20 s.** reset back
3aa20 64 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 72 72 down to the curr
3aa30 65 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a ent value..**.**
3aa40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
3aa50 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 6e te3_status()] an
3aa60 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f d [sqlite3_stmt_
3aa70 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 status()]..*/.SQ
3aa80 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
3aa90 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
3aaa0 20 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 sqlite3_db_stat
3aab0 75 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 us(sqlite3*, int
3aac0 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 2c 20 op, int *pCur,
3aad0 69 6e 74 20 2a 70 48 69 77 74 72 2c 20 69 6e 74 int *pHiwtr, int
3aae0 20 72 65 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a resetFlg);../*.
3aaf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 ** CAPI3REF: Sta
3ab00 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 20 66 tus Parameters f
3ab10 6f 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e or database conn
3ab20 65 63 74 69 6f 6e 73 20 7b 48 31 37 35 32 30 7d ections {H17520}
3ab30 20 3c 48 31 37 35 30 30 3e 0a 2a 2a 20 45 58 50 <H17500>.** EXP
3ab40 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
3ab50 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
3ab60 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
3ab70 65 20 69 6e 74 65 67 65 72 20 22 76 65 72 62 73 e integer "verbs
3ab80 22 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 " that can be pa
3ab90 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 73 ssed as.** the s
3aba0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
3abb0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 o the [sqlite3_d
3abc0 62 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65 b_status()] inte
3abd0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
3abe0 20 76 65 72 62 73 20 6d 61 79 20 62 65 20 61 64 verbs may be ad
3abf0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
3ac00 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
3ac10 2e 20 45 78 69 73 74 69 6e 67 20 76 65 72 62 73 . Existing verbs
3ac20 0a 2a 2a 20 6d 69 67 68 74 20 62 65 20 64 69 73 .** might be dis
3ac30 63 6f 6e 74 69 6e 75 65 64 2e 20 41 70 70 6c 69 continued. Appli
3ac40 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 63 cations should c
3ac50 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
3ac60 63 6f 64 65 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 code from.** [sq
3ac70 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 lite3_db_status(
3ac80 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
3ac90 74 68 61 74 20 74 68 65 20 63 61 6c 6c 20 77 6f that the call wo
3aca0 72 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 rked..** The [sq
3acb0 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 lite3_db_status(
3acc0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c )] interface wil
3acd0 6c 20 72 65 74 75 72 6e 20 61 20 6e 6f 6e 2d 7a l return a non-z
3ace0 65 72 6f 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a ero error code.*
3acf0 2a 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e * if a discontin
3ad00 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
3ad10 65 64 20 76 65 72 62 20 69 73 20 69 6e 76 6f 6b ed verb is invok
3ad20 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ed..**.** <dl>.*
3ad30 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 53 * <dt>SQLITE_DBS
3ad40 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f TATUS_LOOKASIDE_
3ad50 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 USED</dt>.** <dd
3ad60 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 >This parameter
3ad70 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
3ad80 65 72 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 er of lookaside
3ad90 6d 65 6d 6f 72 79 20 73 6c 6f 74 73 20 63 75 72 memory slots cur
3ada0 72 65 6e 74 6c 79 0a 2a 2a 20 63 68 65 63 6b 65 rently.** checke
3adb0 64 20 6f 75 74 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c d out.</dd>.** <
3adc0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
3add0 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f SQLITE_DBSTATUS_
3ade0 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 20 20 LOOKASIDE_USED
3adf0 20 20 20 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 0.../*.** CAP
3ae00 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 I3REF: Prepared
3ae10 53 74 61 74 65 6d 65 6e 74 20 53 74 61 74 75 73 Statement Status
3ae20 20 7b 48 31 37 35 35 30 7d 20 3c 53 36 30 32 30 {H17550} <S6020
3ae30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
3ae40 41 4c 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 70 72 AL.**.** Each pr
3ae50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
3ae60 20 6d 61 69 6e 74 61 69 6e 73 20 76 61 72 69 6f maintains vario
3ae70 75 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 us.** [SQLITE_ST
3ae80 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20 7c 20 MTSTATUS_SORT |
3ae90 63 6f 75 6e 74 65 72 73 5d 20 74 68 61 74 20 6d counters] that m
3aea0 65 61 73 75 72 65 20 74 68 65 20 6e 75 6d 62 65 easure the numbe
3aeb0 72 0a 2a 2a 20 6f 66 20 74 69 6d 65 73 20 69 74 r.** of times it
3aec0 20 68 61 73 20 70 65 72 66 6f 72 6d 65 64 20 73 has performed s
3aed0 70 65 63 69 66 69 63 20 6f 70 65 72 61 74 69 6f pecific operatio
3aee0 6e 73 2e 20 20 54 68 65 73 65 20 63 6f 75 6e 74 ns. These count
3aef0 65 72 73 20 63 61 6e 0a 2a 2a 20 62 65 20 75 73 ers can.** be us
3af00 65 64 20 74 6f 20 6d 6f 6e 69 74 6f 72 20 74 68 ed to monitor th
3af10 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 63 68 e performance ch
3af20 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 aracteristics of
3af30 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a the prepared.**
3af40 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 46 6f statements. Fo
3af50 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 r example, if th
3af60 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 61 62 6c e number of tabl
3af70 65 20 73 74 65 70 73 20 67 72 65 61 74 6c 79 20 e steps greatly
3af80 65 78 63 65 65 64 73 0a 2a 2a 20 74 68 65 20 6e exceeds.** the n
3af90 75 6d 62 65 72 20 6f 66 20 74 61 62 6c 65 20 73 umber of table s
3afa0 65 61 72 63 68 65 73 20 6f 72 20 72 65 73 75 6c earches or resul
3afb0 74 20 72 6f 77 73 2c 20 74 68 61 74 20 77 6f 75 t rows, that wou
3afc0 6c 64 20 74 65 6e 64 20 74 6f 20 69 6e 64 69 63 ld tend to indic
3afd0 61 74 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ate.** that the
3afe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
3aff0 6e 74 20 69 73 20 75 73 69 6e 67 20 61 20 66 75 nt is using a fu
3b000 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 20 72 61 ll table scan ra
3b010 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 61 6e 20 ther than.** an
3b020 69 6e 64 65 78 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 index. .**.** T
3b030 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
3b040 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
3b050 65 20 61 6e 64 20 72 65 73 65 74 20 63 6f 75 6e e and reset coun
3b060 74 65 72 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a ter values from.
3b070 2a 2a 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 ** a [prepared s
3b080 74 61 74 65 6d 65 6e 74 5d 2e 20 20 54 68 65 20 tatement]. The
3b090 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
3b0a0 73 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 s the prepared s
3b0b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 62 6a 65 tatement.** obje
3b0c0 63 74 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f ct to be interro
3b0d0 67 61 74 65 64 2e 20 20 54 68 65 20 73 65 63 6f gated. The seco
3b0e0 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 nd argument.** i
3b0f0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 s an integer cod
3b100 65 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 63 e for a specific
3b110 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 [SQLITE_STMTSTA
3b120 54 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 TUS_SORT | count
3b130 65 72 5d 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 er].** to be int
3b140 65 72 72 6f 67 61 74 65 64 2e 20 0a 2a 2a 20 54 errogated. .** T
3b150 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 he current value
3b160 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 of the requeste
3b170 64 20 63 6f 75 6e 74 65 72 20 69 73 20 72 65 74 d counter is ret
3b180 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 urned..** If the
3b190 20 72 65 73 65 74 46 6c 67 20 69 73 20 74 72 75 resetFlg is tru
3b1a0 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 75 6e e, then the coun
3b1b0 74 65 72 20 69 73 20 72 65 73 65 74 20 74 6f 20 ter is reset to
3b1c0 7a 65 72 6f 20 61 66 74 65 72 20 74 68 69 73 0a zero after this.
3b1d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c ** interface cal
3b1e0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a l returns..**.**
3b1f0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
3b200 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 6e te3_status()] an
3b210 64 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 d [sqlite3_db_st
3b220 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 atus()]..*/.SQLI
3b230 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 TE_API SQLITE_EX
3b240 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
3b250 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 qlite3_stmt_stat
3b260 75 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a us(sqlite3_stmt*
3b270 2c 20 69 6e 74 20 6f 70 2c 69 6e 74 20 72 65 73 , int op,int res
3b280 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 etFlg);../*.** C
3b290 41 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 API3REF: Status
3b2a0 50 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 70 Parameters for p
3b2b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
3b2c0 74 73 20 7b 48 31 37 35 37 30 7d 20 3c 48 31 37 ts {H17570} <H17
3b2d0 35 35 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 550>.** EXPERIME
3b2e0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 NTAL.**.** These
3b2f0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
3b300 63 72 6f 73 20 64 65 66 69 6e 65 20 69 6e 74 65 cros define inte
3b310 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 6e ger codes that n
3b320 61 6d 65 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 ame counter.** v
3b330 61 6c 75 65 73 20 61 73 73 6f 63 69 61 74 65 64 alues associated
3b340 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 with the [sqlit
3b350 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 29 e3_stmt_status()
3b360 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 ] interface..**
3b370 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 The meanings of
3b380 74 68 65 20 76 61 72 69 6f 75 73 20 63 6f 75 6e the various coun
3b390 74 65 72 73 20 61 72 65 20 61 73 20 66 6f 6c 6c ters are as foll
3b3a0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ows:.**.** <dl>.
3b3b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
3b3c0 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 MTSTATUS_FULLSCA
3b3d0 4e 5f 53 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c N_STEP</dt>.** <
3b3e0 64 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 6e dd>This is the n
3b3f0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 umber of times t
3b400 68 61 74 20 53 51 4c 69 74 65 20 68 61 73 20 73 hat SQLite has s
3b410 74 65 70 70 65 64 20 66 6f 72 77 61 72 64 20 69 tepped forward i
3b420 6e 0a 2a 2a 20 61 20 74 61 62 6c 65 20 61 73 20 n.** a table as
3b430 70 61 72 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 part of a full t
3b440 61 62 6c 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 able scan. Larg
3b450 65 20 6e 75 6d 62 65 72 73 20 66 6f 72 20 74 68 e numbers for th
3b460 69 73 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 is counter.** ma
3b470 79 20 69 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 y indicate oppor
3b480 74 75 6e 69 74 69 65 73 20 66 6f 72 20 70 65 72 tunities for per
3b490 66 6f 72 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 formance improve
3b4a0 6d 65 6e 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a ment through .**
3b4b0 20 63 61 72 65 66 75 6c 20 75 73 65 20 6f 66 20 careful use of
3b4c0 69 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a indices.</dd>.**
3b4d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
3b4e0 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 3c 2f TMTSTATUS_SORT</
3b4f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
3b500 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
3b510 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 sort operations
3b520 20 74 68 61 74 20 68 61 76 65 20 6f 63 63 75 72 that have occur
3b530 72 65 64 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 red..** A non-ze
3b540 72 6f 20 76 61 6c 75 65 20 69 6e 20 74 68 69 73 ro value in this
3b550 20 63 6f 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 counter may ind
3b560 69 63 61 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 icate an opportu
3b570 6e 69 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f nity to.** impro
3b580 76 65 6d 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e vement performan
3b590 63 65 20 74 68 72 6f 75 67 68 20 63 61 72 65 66 ce through caref
3b5a0 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 ul use of indice
3b5b0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f s.</dd>.**.** </
3b5c0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
3b5d0 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 QLITE_STMTSTATUS
3b5e0 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 20 20 _FULLSCAN_STEP
3b5f0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
3b600 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 ITE_STMTSTATUS_S
3b610 4f 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 ORT
3b620 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 2../*.** CAPI3R
3b630 45 46 3a 20 43 75 73 74 6f 6d 20 50 61 67 65 20 EF: Custom Page
3b640 43 61 63 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 Cache Object.**
3b650 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
3b660 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 ** The sqlite3_p
3b670 63 61 63 68 65 20 74 79 70 65 20 69 73 20 6f 70 cache type is op
3b680 61 71 75 65 2e 20 20 49 74 20 69 73 20 69 6d 70 aque. It is imp
3b690 6c 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 lemented by.** t
3b6a0 68 65 20 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 he pluggable mod
3b6b0 75 6c 65 2e 20 20 54 68 65 20 53 51 4c 69 74 65 ule. The SQLite
3b6c0 20 63 6f 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f core has no kno
3b6d0 77 6c 65 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 wledge of.** its
3b6e0 20 73 69 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 size or interna
3b6f0 6c 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 l structure and
3b700 6e 65 76 65 72 20 64 65 61 6c 73 20 77 69 74 68 never deals with
3b710 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f the.** sqlite3_
3b720 70 63 61 63 68 65 20 6f 62 6a 65 63 74 20 65 78 pcache object ex
3b730 63 65 70 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 cept by holding
3b740 61 6e 64 20 70 61 73 73 69 6e 67 20 70 6f 69 6e and passing poin
3b750 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f ters.** to the o
3b760 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 bject..**.** See
3b770 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
3b780 5f 6d 65 74 68 6f 64 73 5d 20 66 6f 72 20 61 64 _methods] for ad
3b790 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
3b7a0 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
3b7b0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
3b7c0 70 63 61 63 68 65 20 73 71 6c 69 74 65 33 5f 70 pcache sqlite3_p
3b7d0 63 61 63 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 cache;../*.** CA
3b7e0 50 49 33 52 45 46 3a 20 41 70 70 6c 69 63 61 74 PI3REF: Applicat
3b7f0 69 6f 6e 20 44 65 66 69 6e 65 64 20 50 61 67 65 ion Defined Page
3b800 20 43 61 63 68 65 2e 0a 2a 2a 20 4b 45 59 57 4f Cache..** KEYWO
3b810 52 44 53 3a 20 7b 70 61 67 65 20 63 61 63 68 65 RDS: {page cache
3b820 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 }.** EXPERIMENTA
3b830 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c L.**.** The [sql
3b840 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
3b850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
3b860 48 45 5d 2c 20 2e 2e 2e 29 20 69 6e 74 65 72 66 HE], ...) interf
3b870 61 63 65 20 63 61 6e 0a 2a 2a 20 72 65 67 69 73 ace can.** regis
3b880 74 65 72 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ter an alternati
3b890 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d ve page cache im
3b8a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 62 79 20 plementation by
3b8b0 70 61 73 73 69 6e 67 20 69 6e 20 61 6e 20 0a 2a passing in an .*
3b8c0 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
3b8d0 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 e sqlite3_pcache
3b8e0 5f 6d 65 74 68 6f 64 73 20 73 74 72 75 63 74 75 _methods structu
3b8f0 72 65 2e 20 54 68 65 20 6d 61 6a 6f 72 69 74 79 re. The majority
3b900 20 6f 66 20 74 68 65 20 0a 2a 2a 20 68 65 61 70 of the .** heap
3b910 20 6d 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 memory used by
3b920 53 51 4c 69 74 65 20 69 73 20 75 73 65 64 20 62 SQLite is used b
3b930 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 y the page cache
3b940 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 20 72 to cache data r
3b950 65 61 64 20 0a 2a 2a 20 66 72 6f 6d 2c 20 6f 72 ead .** from, or
3b960 20 72 65 61 64 79 20 74 6f 20 62 65 20 77 72 69 ready to be wri
3b970 74 74 65 6e 20 74 6f 2c 20 74 68 65 20 64 61 74 tten to, the dat
3b980 61 62 61 73 65 20 66 69 6c 65 2e 20 42 79 20 69 abase file. By i
3b990 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61 20 0a 2a mplementing a .*
3b9a0 2a 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 * custom page ca
3b9b0 63 68 65 20 75 73 69 6e 67 20 74 68 69 73 20 41 che using this A
3b9c0 50 49 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 PI, an applicati
3b9d0 6f 6e 20 63 61 6e 20 63 6f 6e 74 72 6f 6c 20 6d on can control m
3b9e0 6f 72 65 20 0a 2a 2a 20 70 72 65 63 69 73 65 6c ore .** precisel
3b9f0 79 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 y the amount of
3ba00 6d 65 6d 6f 72 79 20 63 6f 6e 73 75 6d 65 64 20 memory consumed
3ba10 62 79 20 53 51 4c 69 74 65 2c 20 74 68 65 20 77 by SQLite, the w
3ba20 61 79 20 69 6e 20 77 68 69 63 68 20 0a 2a 2a 20 ay in which .**
3ba30 74 68 61 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 that memory is a
3ba40 6c 6c 6f 63 61 74 65 64 20 61 6e 64 20 72 65 6c llocated and rel
3ba50 65 61 73 65 64 2c 20 61 6e 64 20 74 68 65 20 70 eased, and the p
3ba60 6f 6c 69 63 69 65 73 20 75 73 65 64 20 74 6f 20 olicies used to
3ba70 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 20 65 78 .** determine ex
3ba80 61 63 74 6c 79 20 77 68 69 63 68 20 70 61 72 74 actly which part
3ba90 73 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 s of a database
3baa0 66 69 6c 65 20 61 72 65 20 63 61 63 68 65 64 20 file are cached
3bab0 61 6e 64 20 66 6f 72 20 0a 2a 2a 20 68 6f 77 20 and for .** how
3bac0 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 long..**.** The
3bad0 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 contents of the
3bae0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
3baf0 65 74 68 6f 64 73 20 73 74 72 75 63 74 75 72 65 ethods structure
3bb00 20 61 72 65 20 63 6f 70 69 65 64 20 74 6f 20 61 are copied to a
3bb10 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 62 75 n.** internal bu
3bb20 66 66 65 72 20 62 79 20 53 51 4c 69 74 65 20 77 ffer by SQLite w
3bb30 69 74 68 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 ithin the call t
3bb40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
3bb50 67 5d 2e 20 20 48 65 6e 63 65 0a 2a 2a 20 74 68 g]. Hence.** th
3bb60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 e application ma
3bb70 79 20 64 69 73 63 61 72 64 20 74 68 65 20 70 61 y discard the pa
3bb80 72 61 6d 65 74 65 72 20 61 66 74 65 72 20 74 68 rameter after th
3bb90 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 e call to.** [sq
3bba0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
3bbb0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 returns..**.** T
3bbc0 68 65 20 78 49 6e 69 74 28 29 20 6d 65 74 68 6f he xInit() metho
3bbd0 64 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 63 65 d is called once
3bbe0 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74 for each call t
3bbf0 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 o [sqlite3_initi
3bc00 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 28 75 73 75 alize()].** (usu
3bc10 61 6c 6c 79 20 6f 6e 6c 79 20 6f 6e 63 65 20 64 ally only once d
3bc20 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 uring the lifeti
3bc30 6d 65 20 6f 66 20 74 68 65 20 70 72 6f 63 65 73 me of the proces
3bc40 73 29 2e 20 49 74 20 69 73 20 70 61 73 73 65 64 s). It is passed
3bc50 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 .** a copy of th
3bc60 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 e sqlite3_pcache
3bc70 5f 6d 65 74 68 6f 64 73 2e 70 41 72 67 20 76 61 _methods.pArg va
3bc80 6c 75 65 2e 20 49 74 20 63 61 6e 20 62 65 20 75 lue. It can be u
3bc90 73 65 64 20 74 6f 20 73 65 74 0a 2a 2a 20 75 70 sed to set.** up
3bca0 20 67 6c 6f 62 61 6c 20 73 74 72 75 63 74 75 72 global structur
3bcb0 65 73 20 61 6e 64 20 6d 75 74 65 78 65 73 20 72 es and mutexes r
3bcc0 65 71 75 69 72 65 64 20 62 79 20 74 68 65 20 63 equired by the c
3bcd0 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 ustom page cache
3bce0 20 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 .** implementat
3bcf0 69 6f 6e 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ion. .**.** The
3bd00 78 53 68 75 74 64 6f 77 6e 28 29 20 6d 65 74 68 xShutdown() meth
3bd10 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 66 72 6f od is called fro
3bd20 6d 20 77 69 74 68 69 6e 20 5b 73 71 6c 69 74 65 m within [sqlite
3bd30 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2c 20 0a 3_shutdown()], .
3bd40 2a 2a 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 ** if the applic
3bd50 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 74 68 ation invokes th
3bd60 69 73 20 41 50 49 2e 20 49 74 20 63 61 6e 20 62 is API. It can b
3bd70 65 20 75 73 65 64 20 74 6f 20 63 6c 65 61 6e 20 e used to clean
3bd80 75 70 20 0a 2a 2a 20 61 6e 79 20 6f 75 74 73 74 up .** any outst
3bd90 61 6e 64 69 6e 67 20 72 65 73 6f 75 72 63 65 73 anding resources
3bda0 20 62 65 66 6f 72 65 20 70 72 6f 63 65 73 73 20 before process
3bdb0 73 68 75 74 64 6f 77 6e 2c 20 69 66 20 72 65 71 shutdown, if req
3bdc0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c uired..**.** SQL
3bdd0 69 74 65 20 68 6f 6c 64 73 20 61 20 5b 53 51 4c ite holds a [SQL
3bde0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
3bdf0 49 56 45 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 IVE] mutex when
3be00 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 it invokes.** th
3be10 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 e xInit method,
3be20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 so the xInit met
3be30 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 hod need not be
3be40 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 threadsafe. The
3be50 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 .** xShutdown me
3be60 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c thod is only cal
3be70 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 led from [sqlite
3be80 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 3_shutdown()] so
3be90 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 it does.** not
3bea0 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 need to be threa
3beb0 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 41 dsafe either. A
3bec0 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 ll other methods
3bed0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 must be threads
3bee0 61 66 65 0a 2a 2a 20 69 6e 20 6d 75 6c 74 69 74 afe.** in multit
3bef0 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 hreaded applicat
3bf00 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ions..**.** SQLi
3bf10 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e te will never in
3bf20 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 voke xInit() mor
3bf30 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 e than once with
3bf40 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 out an interveni
3bf50 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 ng.** call to xS
3bf60 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a hutdown()..**.**
3bf70 20 54 68 65 20 78 43 72 65 61 74 65 28 29 20 6d The xCreate() m
3bf80 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f ethod is used to
3bf90 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 construct a new
3bfa0 20 63 61 63 68 65 20 69 6e 73 74 61 6e 63 65 2e cache instance.
3bfb0 20 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c SQLite.** will
3bfc0 20 74 79 70 69 63 61 6c 6c 79 20 63 72 65 61 74 typically creat
3bfd0 65 20 6f 6e 65 20 63 61 63 68 65 20 69 6e 73 74 e one cache inst
3bfe0 61 6e 63 65 20 66 6f 72 20 65 61 63 68 20 6f 70 ance for each op
3bff0 65 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 en database file
3c000 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 74 68 69 73 ,.** though this
3c010 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 is not guarante
3c020 65 64 2e 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 ed. The.** first
3c030 20 70 61 72 61 6d 65 74 65 72 2c 20 73 7a 50 61 parameter, szPa
3c040 67 65 2c 20 69 73 20 74 68 65 20 73 69 7a 65 20 ge, is the size
3c050 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 in bytes of the
3c060 70 61 67 65 73 20 74 68 61 74 20 6d 75 73 74 0a pages that must.
3c070 2a 2a 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 ** be allocated
3c080 62 79 20 74 68 65 20 63 61 63 68 65 2e 20 20 73 by the cache. s
3c090 7a 50 61 67 65 20 77 69 6c 6c 20 6e 6f 74 20 62 zPage will not b
3c0a0 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f e a power of two
3c0b0 2e 20 20 73 7a 50 61 67 65 0a 2a 2a 20 77 69 6c . szPage.** wil
3c0c0 6c 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 l the page size
3c0d0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
3c0e0 66 69 6c 65 20 74 68 61 74 20 69 73 20 74 6f 20 file that is to
3c0f0 62 65 20 63 61 63 68 65 64 20 70 6c 75 73 20 61 be cached plus a
3c100 6e 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 20 28 n.** increment (
3c110 68 65 72 65 20 63 61 6c 6c 65 64 20 22 52 22 29 here called "R")
3c120 20 6f 66 20 61 62 6f 75 74 20 31 30 30 20 6f 72 of about 100 or
3c130 20 32 30 30 2e 20 20 53 51 4c 69 74 65 20 77 69 200. SQLite wi
3c140 6c 6c 20 75 73 65 20 74 68 65 0a 2a 2a 20 65 78 ll use the.** ex
3c150 74 72 61 20 52 20 62 79 74 65 73 20 6f 6e 20 65 tra R bytes on e
3c160 61 63 68 20 70 61 67 65 20 74 6f 20 73 74 6f 72 ach page to stor
3c170 65 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 e metadata about
3c180 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a the underlying.
3c190 2a 2a 20 64 61 74 61 62 61 73 65 20 70 61 67 65 ** database page
3c1a0 20 6f 6e 20 64 69 73 6b 2e 20 20 54 68 65 20 76 on disk. The v
3c1b0 61 6c 75 65 20 6f 66 20 52 20 64 65 70 65 6e 64 alue of R depend
3c1c0 73 0a 2a 2a 20 6f 6e 20 74 68 65 20 53 51 4c 69 s.** on the SQLi
3c1d0 74 65 20 76 65 72 73 69 6f 6e 2c 20 74 68 65 20 te version, the
3c1e0 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c target platform,
3c1f0 20 61 6e 64 20 68 6f 77 20 53 51 4c 69 74 65 20 and how SQLite
3c200 77 61 73 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a was compiled..**
3c210 20 52 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 66 R is constant f
3c220 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
3c230 62 75 69 6c 64 20 6f 66 20 53 51 4c 69 74 65 2e build of SQLite.
3c240 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 The second arg
3c250 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 43 72 65 ument to.** xCre
3c260 61 74 65 28 29 2c 20 62 50 75 72 67 65 61 62 6c ate(), bPurgeabl
3c270 65 2c 20 69 73 20 74 72 75 65 20 69 66 20 74 68 e, is true if th
3c280 65 20 63 61 63 68 65 20 62 65 69 6e 67 20 63 72 e cache being cr
3c290 65 61 74 65 64 20 77 69 6c 6c 0a 2a 2a 20 62 65 eated will.** be
3c2a0 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 used to cache d
3c2b0 61 74 61 62 61 73 65 20 70 61 67 65 73 20 6f 66 atabase pages of
3c2c0 20 61 20 66 69 6c 65 20 73 74 6f 72 65 64 20 6f a file stored o
3c2d0 6e 20 64 69 73 6b 2c 20 6f 72 0a 2a 2a 20 66 61 n disk, or.** fa
3c2e0 6c 73 65 20 69 66 20 69 74 20 69 73 20 75 73 65 lse if it is use
3c2f0 64 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f d for an in-memo
3c300 72 79 20 64 61 74 61 62 61 73 65 2e 20 54 68 65 ry database. The
3c310 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
3c320 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 6e 6f ation.** does no
3c330 74 20 68 61 76 65 20 74 6f 20 64 6f 20 61 6e 79 t have to do any
3c340 74 68 69 6e 67 20 73 70 65 63 69 61 6c 20 62 61 thing special ba
3c350 73 65 64 20 77 69 74 68 20 74 68 65 20 76 61 6c sed with the val
3c360 75 65 20 6f 66 20 62 50 75 72 67 65 61 62 6c 65 ue of bPurgeable
3c370 3b 0a 2a 2a 20 69 74 20 69 73 20 70 75 72 65 6c ;.** it is purel
3c380 79 20 61 64 76 69 73 6f 72 79 2e 20 20 4f 6e 20 y advisory. On
3c390 61 20 63 61 63 68 65 20 77 68 65 72 65 20 62 50 a cache where bP
3c3a0 75 72 67 65 61 62 6c 65 20 69 73 20 66 61 6c 73 urgeable is fals
3c3b0 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a e, SQLite will.*
3c3c0 2a 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 * never invoke x
3c3d0 55 6e 70 69 6e 28 29 20 65 78 63 65 70 74 20 74 Unpin() except t
3c3e0 6f 20 64 65 6c 69 62 65 72 61 74 65 6c 79 20 64 o deliberately d
3c3f0 65 6c 65 74 65 20 61 20 70 61 67 65 2e 0a 2a 2a elete a page..**
3c400 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
3c410 20 61 20 63 61 63 68 65 20 63 72 65 61 74 65 64 a cache created
3c420 20 77 69 74 68 20 62 50 75 72 67 65 61 62 6c 65 with bPurgeable
3c430 20 73 65 74 20 74 6f 20 66 61 6c 73 65 20 77 69 set to false wi
3c440 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 63 6f 6e 74 ll.** never cont
3c450 61 69 6e 20 61 6e 79 20 75 6e 70 69 6e 6e 65 64 ain any unpinned
3c460 20 70 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 pages..**.** Th
3c470 65 20 78 43 61 63 68 65 73 69 7a 65 28 29 20 6d e xCachesize() m
3c480 65 74 68 6f 64 20 6d 61 79 20 62 65 20 63 61 6c ethod may be cal
3c490 6c 65 64 20 61 74 20 61 6e 79 20 74 69 6d 65 20 led at any time
3c4a0 62 79 20 53 51 4c 69 74 65 20 74 6f 20 73 65 74 by SQLite to set
3c4b0 20 74 68 65 0a 2a 2a 20 73 75 67 67 65 73 74 65 the.** suggeste
3c4c0 64 20 6d 61 78 69 6d 75 6d 20 63 61 63 68 65 2d d maximum cache-
3c4d0 73 69 7a 65 20 28 6e 75 6d 62 65 72 20 6f 66 20 size (number of
3c4e0 70 61 67 65 73 20 73 74 6f 72 65 64 20 62 79 29 pages stored by)
3c4f0 20 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 69 6e the cache.** in
3c500 73 74 61 6e 63 65 20 70 61 73 73 65 64 20 61 73 stance passed as
3c510 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
3c520 65 6e 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 ent. This is the
3c530 20 76 61 6c 75 65 20 63 6f 6e 66 69 67 75 72 65 value configure
3c540 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 53 d using.** the S
3c550 51 4c 69 74 65 20 22 5b 50 52 41 47 4d 41 20 63 QLite "[PRAGMA c
3c560 61 63 68 65 5f 73 69 7a 65 5d 22 20 63 6f 6d 6d ache_size]" comm
3c570 61 6e 64 2e 20 41 73 20 77 69 74 68 20 74 68 65 and. As with the
3c580 20 62 50 75 72 67 65 61 62 6c 65 20 70 61 72 61 bPurgeable para
3c590 6d 65 74 65 72 2c 0a 2a 2a 20 74 68 65 20 69 6d meter,.** the im
3c5a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
3c5b0 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 not required to
3c5c0 64 6f 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 do anything with
3c5d0 20 74 68 69 73 0a 2a 2a 20 76 61 6c 75 65 3b 20 this.** value;
3c5e0 69 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f it is advisory o
3c5f0 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 nly..**.** The x
3c600 50 61 67 65 63 6f 75 6e 74 28 29 20 6d 65 74 68 Pagecount() meth
3c610 6f 64 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e od should return
3c620 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
3c630 61 67 65 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a ages currently.*
3c640 2a 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 * stored in the
3c650 63 61 63 68 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 cache..** .** Th
3c660 65 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 6f e xFetch() metho
3c670 64 20 69 73 20 75 73 65 64 20 74 6f 20 66 65 74 d is used to fet
3c680 63 68 20 61 20 70 61 67 65 20 61 6e 64 20 72 65 ch a page and re
3c690 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 turn a pointer t
3c6a0 6f 20 69 74 2e 20 0a 2a 2a 20 41 20 27 70 61 67 o it. .** A 'pag
3c6b0 65 27 2c 20 69 6e 20 74 68 69 73 20 63 6f 6e 74 e', in this cont
3c6c0 65 78 74 2c 20 69 73 20 61 20 62 75 66 66 65 72 ext, is a buffer
3c6d0 20 6f 66 20 73 7a 50 61 67 65 20 62 79 74 65 73 of szPage bytes
3c6e0 20 61 6c 69 67 6e 65 64 20 61 74 20 61 6e 0a 2a aligned at an.*
3c6f0 2a 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 * 8-byte boundar
3c700 79 2e 20 54 68 65 20 70 61 67 65 20 74 6f 20 62 y. The page to b
3c710 65 20 66 65 74 63 68 65 64 20 69 73 20 64 65 74 e fetched is det
3c720 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 6b ermined by the k
3c730 65 79 2e 20 54 68 65 0a 2a 2a 20 6d 69 6d 69 6d ey. The.** mimim
3c740 75 6d 20 6b 65 79 20 76 61 6c 75 65 20 69 73 20 um key value is
3c750 31 2e 20 41 66 74 65 72 20 69 74 20 68 61 73 20 1. After it has
3c760 62 65 65 6e 20 72 65 74 72 69 65 76 65 64 20 75 been retrieved u
3c770 73 69 6e 67 20 78 46 65 74 63 68 2c 20 74 68 65 sing xFetch, the
3c780 20 70 61 67 65 20 0a 2a 2a 20 69 73 20 63 6f 6e page .** is con
3c790 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 22 70 sidered to be "p
3c7a0 69 6e 6e 65 64 22 2e 0a 2a 2a 0a 2a 2a 20 49 66 inned"..**.** If
3c7b0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70 the requested p
3c7c0 61 67 65 20 69 73 20 61 6c 72 65 61 64 79 20 69 age is already i
3c7d0 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 n the page cache
3c7e0 2c 20 74 68 65 6e 20 74 68 65 20 70 61 67 65 20 , then the page
3c7f0 63 61 63 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 cache.** impleme
3c800 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 ntation must ret
3c810 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f urn a pointer to
3c820 20 74 68 65 20 70 61 67 65 20 62 75 66 66 65 72 the page buffer
3c830 20 77 69 74 68 20 69 74 73 20 63 6f 6e 74 65 6e with its conten
3c840 74 0a 2a 2a 20 69 6e 74 61 63 74 2e 20 20 49 66 t.** intact. If
3c850 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70 the requested p
3c860 61 67 65 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 age is not alrea
3c870 64 79 20 69 6e 20 74 68 65 20 63 61 63 68 65 2c dy in the cache,
3c880 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 62 65 68 then the.** beh
3c890 61 76 69 6f 72 20 6f 66 20 74 68 65 20 63 61 63 avior of the cac
3c8a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
3c8b0 6e 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 n is determined
3c8c0 62 79 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 by the value of
3c8d0 74 68 65 0a 2a 2a 20 63 72 65 61 74 65 46 6c 61 the.** createFla
3c8e0 67 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 g parameter pass
3c8f0 65 64 20 74 6f 20 78 46 65 74 63 68 2c 20 61 63 ed to xFetch, ac
3c900 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 66 cording to the f
3c910 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 3a 0a ollowing table:.
3c920 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 **.** <table bor
3c930 64 65 72 3d 31 20 77 69 64 74 68 3d 38 35 25 20 der=1 width=85%
3c940 61 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 2a 2a align=center>.**
3c950 20 3c 74 72 3e 3c 74 68 3e 20 63 72 65 61 74 65 <tr><th> create
3c960 46 6c 61 67 20 3c 74 68 3e 20 42 65 68 61 76 69 Flag <th> Behavi
3c970 6f 75 72 20 77 68 65 6e 20 70 61 67 65 20 69 73 our when page is
3c980 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69 6e 20 not already in
3c990 63 61 63 68 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 cache.** <tr><td
3c9a0 3e 20 30 20 3c 74 64 3e 20 44 6f 20 6e 6f 74 20 > 0 <td> Do not
3c9b0 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 20 70 allocate a new p
3c9c0 61 67 65 2e 20 20 52 65 74 75 72 6e 20 4e 55 4c age. Return NUL
3c9d0 4c 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 31 L..** <tr><td> 1
3c9e0 20 3c 74 64 3e 20 41 6c 6c 6f 63 61 74 65 20 61 <td> Allocate a
3c9f0 20 6e 65 77 20 70 61 67 65 20 69 66 20 69 74 20 new page if it
3ca00 65 61 73 79 20 61 6e 64 20 63 6f 6e 76 65 6e 69 easy and conveni
3ca10 65 6e 74 20 74 6f 20 64 6f 20 73 6f 2e 0a 2a 2a ent to do so..**
3ca20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ca30 20 4f 74 68 65 72 77 69 73 65 20 72 65 74 75 72 Otherwise retur
3ca40 6e 20 4e 55 4c 4c 2e 0a 2a 2a 20 3c 74 72 3e 3c n NULL..** <tr><
3ca50 74 64 3e 20 32 20 3c 74 64 3e 20 4d 61 6b 65 20 td> 2 <td> Make
3ca60 65 76 65 72 79 20 65 66 66 6f 72 74 20 74 6f 20 every effort to
3ca70 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 20 70 allocate a new p
3ca80 61 67 65 2e 20 20 4f 6e 6c 79 20 72 65 74 75 72 age. Only retur
3ca90 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 n.**
3caa0 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 61 6c 6c NULL if all
3cab0 6f 63 61 74 69 6e 67 20 61 20 6e 65 77 20 70 61 ocating a new pa
3cac0 67 65 20 69 73 20 65 66 66 65 63 74 69 76 65 6c ge is effectivel
3cad0 79 20 69 6d 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a y impossible..**
3cae0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 </table>.**.**
3caf0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 72 6d SQLite will norm
3cb00 61 6c 6c 79 20 69 6e 76 6f 6b 65 20 78 46 65 74 ally invoke xFet
3cb10 63 68 28 29 20 77 69 74 68 20 61 20 63 72 65 61 ch() with a crea
3cb20 74 65 46 6c 61 67 20 6f 66 20 30 20 6f 72 20 31 teFlag of 0 or 1
3cb30 2e 20 20 49 66 0a 2a 2a 20 61 20 63 61 6c 6c 20 . If.** a call
3cb40 74 6f 20 78 46 65 74 63 68 28 29 20 77 69 74 68 to xFetch() with
3cb50 20 63 72 65 61 74 65 46 6c 61 67 3d 3d 31 20 72 createFlag==1 r
3cb60 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 eturns NULL, the
3cb70 6e 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a n SQLite will.**
3cb80 20 61 74 74 65 6d 70 74 20 74 6f 20 75 6e 70 69 attempt to unpi
3cb90 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 n one or more ca
3cba0 63 68 65 20 70 61 67 65 73 20 62 79 20 73 70 69 che pages by spi
3cbb0 6c 6c 69 6e 67 20 74 68 65 20 63 6f 6e 74 65 6e lling the conten
3cbc0 74 20 6f 66 0a 2a 2a 20 70 69 6e 6e 65 64 20 70 t of.** pinned p
3cbd0 61 67 65 73 20 74 6f 20 64 69 73 6b 20 61 6e 64 ages to disk and
3cbe0 20 73 79 6e 63 68 69 6e 67 20 74 68 65 20 6f 70 synching the op
3cbf0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 erating system d
3cc00 69 73 6b 20 63 61 63 68 65 2e 20 41 66 74 65 72 isk cache. After
3cc10 0a 2a 2a 20 61 74 74 65 6d 70 74 69 6e 67 20 74 .** attempting t
3cc20 6f 20 75 6e 70 69 6e 20 70 61 67 65 73 2c 20 74 o unpin pages, t
3cc30 68 65 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 he xFetch() meth
3cc40 6f 64 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b od will be invok
3cc50 65 64 20 61 67 61 69 6e 20 77 69 74 68 0a 2a 2a ed again with.**
3cc60 20 61 20 63 72 65 61 74 65 46 6c 61 67 20 6f 66 a createFlag of
3cc70 20 32 2e 0a 2a 2a 0a 2a 2a 20 78 55 6e 70 69 6e 2..**.** xUnpin
3cc80 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 () is called by
3cc90 53 51 4c 69 74 65 20 77 69 74 68 20 61 20 70 6f SQLite with a po
3cca0 69 6e 74 65 72 20 74 6f 20 61 20 63 75 72 72 65 inter to a curre
3ccb0 6e 74 6c 79 20 70 69 6e 6e 65 64 20 70 61 67 65 ntly pinned page
3ccc0 0a 2a 2a 20 61 73 20 69 74 73 20 73 65 63 6f 6e .** as its secon
3ccd0 64 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 74 d argument. If t
3cce0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
3ccf0 65 72 2c 20 64 69 73 63 61 72 64 2c 20 69 73 20 er, discard, is
3cd00 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 non-zero,.** the
3cd10 6e 20 74 68 65 20 70 61 67 65 20 73 68 6f 75 6c n the page shoul
3cd20 64 20 62 65 20 65 76 69 63 74 65 64 20 66 72 6f d be evicted fro
3cd30 6d 20 74 68 65 20 63 61 63 68 65 2e 20 49 6e 20 m the cache. In
3cd40 74 68 69 73 20 63 61 73 65 20 53 51 4c 69 74 65 this case SQLite
3cd50 20 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 .** assumes tha
3cd60 74 20 74 68 65 20 6e 65 78 74 20 74 69 6d 65 20 t the next time
3cd70 74 68 65 20 70 61 67 65 20 69 73 20 72 65 74 72 the page is retr
3cd80 69 65 76 65 64 20 66 72 6f 6d 20 74 68 65 20 63 ieved from the c
3cd90 61 63 68 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 ache using.** th
3cda0 65 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 6f e xFetch() metho
3cdb0 64 2c 20 69 74 20 77 69 6c 6c 20 62 65 20 7a 65 d, it will be ze
3cdc0 72 6f 65 64 2e 20 49 66 20 74 68 65 20 64 69 73 roed. If the dis
3cdd0 63 61 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 card parameter i
3cde0 73 0a 2a 2a 20 7a 65 72 6f 2c 20 74 68 65 6e 20 s.** zero, then
3cdf0 74 68 65 20 70 61 67 65 20 69 73 20 63 6f 6e 73 the page is cons
3ce00 69 64 65 72 65 64 20 74 6f 20 62 65 20 75 6e 70 idered to be unp
3ce10 69 6e 6e 65 64 2e 20 54 68 65 20 63 61 63 68 65 inned. The cache
3ce20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
3ce30 2a 2a 20 6d 61 79 20 63 68 6f 6f 73 65 20 74 6f ** may choose to
3ce40 20 65 76 69 63 74 20 75 6e 70 69 6e 6e 65 64 20 evict unpinned
3ce50 70 61 67 65 73 20 61 74 20 61 6e 79 20 74 69 6d pages at any tim
3ce60 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 e..**.** The cac
3ce70 68 65 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 he is not requir
3ce80 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 61 6e ed to perform an
3ce90 79 20 72 65 66 65 72 65 6e 63 65 20 63 6f 75 6e y reference coun
3cea0 74 69 6e 67 2e 20 41 20 73 69 6e 67 6c 65 20 0a ting. A single .
3ceb0 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 55 6e 70 69 ** call to xUnpi
3cec0 6e 28 29 20 75 6e 70 69 6e 73 20 74 68 65 20 70 n() unpins the p
3ced0 61 67 65 20 72 65 67 61 72 64 6c 65 73 73 20 6f age regardless o
3cee0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 f the number of
3cef0 70 72 69 6f 72 20 63 61 6c 6c 73 20 0a 2a 2a 20 prior calls .**
3cf00 74 6f 20 78 46 65 74 63 68 28 29 2e 0a 2a 2a 0a to xFetch()..**.
3cf10 2a 2a 20 54 68 65 20 78 52 65 6b 65 79 28 29 20 ** The xRekey()
3cf20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 method is used t
3cf30 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6b 65 79 o change the key
3cf40 20 76 61 6c 75 65 20 61 73 73 6f 63 69 61 74 65 value associate
3cf50 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 70 61 d with the.** pa
3cf60 67 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ge passed as the
3cf70 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
3cf80 20 66 72 6f 6d 20 6f 6c 64 4b 65 79 20 74 6f 20 from oldKey to
3cf90 6e 65 77 4b 65 79 2e 20 49 66 20 74 68 65 20 63 newKey. If the c
3cfa0 61 63 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 ache.** previous
3cfb0 6c 79 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20 65 ly contains an e
3cfc0 6e 74 72 79 20 61 73 73 6f 63 69 61 74 65 64 20 ntry associated
3cfd0 77 69 74 68 20 6e 65 77 4b 65 79 2c 20 69 74 20 with newKey, it
3cfe0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 69 73 should be.** dis
3cff0 63 61 72 64 65 64 2e 20 41 6e 79 20 70 72 69 6f carded. Any prio
3d000 72 20 63 61 63 68 65 20 65 6e 74 72 79 20 61 73 r cache entry as
3d010 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 6e 65 sociated with ne
3d020 77 4b 65 79 20 69 73 20 67 75 61 72 61 6e 74 65 wKey is guarante
3d030 65 64 20 6e 6f 74 0a 2a 2a 20 74 6f 20 62 65 20 ed not.** to be
3d040 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 pinned..**.** Wh
3d050 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 en SQLite calls
3d060 74 68 65 20 78 54 72 75 6e 63 61 74 65 28 29 20 the xTruncate()
3d070 6d 65 74 68 6f 64 2c 20 74 68 65 20 63 61 63 68 method, the cach
3d080 65 20 6d 75 73 74 20 64 69 73 63 61 72 64 20 61 e must discard a
3d090 6c 6c 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 63 ll.** existing c
3d0a0 61 63 68 65 20 65 6e 74 72 69 65 73 20 77 69 74 ache entries wit
3d0b0 68 20 70 61 67 65 20 6e 75 6d 62 65 72 73 20 28 h page numbers (
3d0c0 6b 65 79 73 29 20 67 72 65 61 74 65 72 20 74 68 keys) greater th
3d0d0 61 6e 20 6f 72 20 65 71 75 61 6c 0a 2a 2a 20 74 an or equal.** t
3d0e0 6f 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 o the value of t
3d0f0 68 65 20 69 4c 69 6d 69 74 20 70 61 72 61 6d 65 he iLimit parame
3d100 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 78 54 ter passed to xT
3d110 72 75 6e 63 61 74 65 28 29 2e 20 49 66 20 61 6e runcate(). If an
3d120 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 70 61 y.** of these pa
3d130 67 65 73 20 61 72 65 20 70 69 6e 6e 65 64 2c 20 ges are pinned,
3d140 74 68 65 79 20 61 72 65 20 69 6d 70 6c 69 63 69 they are implici
3d150 74 6c 79 20 75 6e 70 69 6e 6e 65 64 2c 20 6d 65 tly unpinned, me
3d160 61 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 74 68 aning that.** th
3d170 65 79 20 63 61 6e 20 62 65 20 73 61 66 65 6c 79 ey can be safely
3d180 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 0a 2a discarded..**.*
3d190 2a 20 54 68 65 20 78 44 65 73 74 72 6f 79 28 29 * The xDestroy()
3d1a0 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 method is used
3d1b0 74 6f 20 64 65 6c 65 74 65 20 61 20 63 61 63 68 to delete a cach
3d1c0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 78 e allocated by x
3d1d0 43 72 65 61 74 65 28 29 2e 0a 2a 2a 20 41 6c 6c Create()..** All
3d1e0 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 resources assoc
3d1f0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 iated with the s
3d200 70 65 63 69 66 69 65 64 20 63 61 63 68 65 20 73 pecified cache s
3d210 68 6f 75 6c 64 20 62 65 20 66 72 65 65 64 2e 20 hould be freed.
3d220 41 66 74 65 72 0a 2a 2a 20 63 61 6c 6c 69 6e 67 After.** calling
3d230 20 74 68 65 20 78 44 65 73 74 72 6f 79 28 29 20 the xDestroy()
3d240 6d 65 74 68 6f 64 2c 20 53 51 4c 69 74 65 20 63 method, SQLite c
3d250 6f 6e 73 69 64 65 72 73 20 74 68 65 20 5b 73 71 onsiders the [sq
3d260 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 5d 0a 2a lite3_pcache*].*
3d270 2a 20 68 61 6e 64 6c 65 20 69 6e 76 61 6c 69 64 * handle invalid
3d280 2c 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 75 , and will not u
3d290 73 65 20 69 74 20 77 69 74 68 20 61 6e 79 20 6f se it with any o
3d2a0 74 68 65 72 20 73 71 6c 69 74 65 33 5f 70 63 61 ther sqlite3_pca
3d2b0 63 68 65 5f 6d 65 74 68 6f 64 73 0a 2a 2a 20 66 che_methods.** f
3d2c0 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 unctions..*/.typ
3d2d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
3d2e0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
3d2f0 64 73 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 ds sqlite3_pcach
3d300 65 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 e_methods;.struc
3d310 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 t sqlite3_pcache
3d320 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 _methods {. voi
3d330 64 20 2a 70 41 72 67 3b 0a 20 20 69 6e 74 20 28 d *pArg;. int (
3d340 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 0a *xInit)(void*);.
3d350 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f void (*xShutdo
3d360 77 6e 29 28 76 6f 69 64 2a 29 3b 0a 20 20 73 71 wn)(void*);. sq
3d370 6c 69 74 65 33 5f 70 63 61 63 68 65 20 2a 28 2a lite3_pcache *(*
3d380 78 43 72 65 61 74 65 29 28 69 6e 74 20 73 7a 50 xCreate)(int szP
3d390 61 67 65 2c 20 69 6e 74 20 62 50 75 72 67 65 61 age, int bPurgea
3d3a0 62 6c 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ble);. void (*x
3d3b0 43 61 63 68 65 73 69 7a 65 29 28 73 71 6c 69 74 Cachesize)(sqlit
3d3c0 65 33 5f 70 63 61 63 68 65 2a 2c 20 69 6e 74 20 e3_pcache*, int
3d3d0 6e 43 61 63 68 65 73 69 7a 65 29 3b 0a 20 20 69 nCachesize);. i
3d3e0 6e 74 20 28 2a 78 50 61 67 65 63 6f 75 6e 74 29 nt (*xPagecount)
3d3f0 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a (sqlite3_pcache*
3d400 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 46 65 );. void *(*xFe
3d410 74 63 68 29 28 73 71 6c 69 74 65 33 5f 70 63 61 tch)(sqlite3_pca
3d420 63 68 65 2a 2c 20 75 6e 73 69 67 6e 65 64 20 6b che*, unsigned k
3d430 65 79 2c 20 69 6e 74 20 63 72 65 61 74 65 46 6c ey, int createFl
3d440 61 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 55 ag);. void (*xU
3d450 6e 70 69 6e 29 28 73 71 6c 69 74 65 33 5f 70 63 npin)(sqlite3_pc
3d460 61 63 68 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e ache*, void*, in
3d470 74 20 64 69 73 63 61 72 64 29 3b 0a 20 20 76 6f t discard);. vo
3d480 69 64 20 28 2a 78 52 65 6b 65 79 29 28 73 71 6c id (*xRekey)(sql
3d490 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 6f ite3_pcache*, vo
3d4a0 69 64 2a 2c 20 75 6e 73 69 67 6e 65 64 20 6f 6c id*, unsigned ol
3d4b0 64 4b 65 79 2c 20 75 6e 73 69 67 6e 65 64 20 6e dKey, unsigned n
3d4c0 65 77 4b 65 79 29 3b 0a 20 20 76 6f 69 64 20 28 ewKey);. void (
3d4d0 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 *xTruncate)(sqli
3d4e0 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e 73 te3_pcache*, uns
3d4f0 69 67 6e 65 64 20 69 4c 69 6d 69 74 29 3b 0a 20 igned iLimit);.
3d500 20 76 6f 69 64 20 28 2a 78 44 65 73 74 72 6f 79 void (*xDestroy
3d510 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 )(sqlite3_pcache
3d520 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 *);.};../*.** CA
3d530 50 49 33 52 45 46 3a 20 4f 6e 6c 69 6e 65 20 42 PI3REF: Online B
3d540 61 63 6b 75 70 20 4f 62 6a 65 63 74 0a 2a 2a 20 ackup Object.**
3d550 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
3d560 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 ** The sqlite3_b
3d570 61 63 6b 75 70 20 6f 62 6a 65 63 74 20 72 65 63 ackup object rec
3d580 6f 72 64 73 20 73 74 61 74 65 20 69 6e 66 6f 72 ords state infor
3d590 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 6e 20 mation about an
3d5a0 6f 6e 67 6f 69 6e 67 0a 2a 2a 20 6f 6e 6c 69 6e ongoing.** onlin
3d5b0 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 e backup operati
3d5c0 6f 6e 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 on. The sqlite3
3d5d0 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 20 69 _backup object i
3d5e0 73 20 63 72 65 61 74 65 64 20 62 79 0a 2a 2a 20 s created by.**
3d5f0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 a call to [sqlit
3d600 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 e3_backup_init()
3d610 5d 20 61 6e 64 20 69 73 20 64 65 73 74 72 6f 79 ] and is destroy
3d620 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 0a ed by a call to.
3d630 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b ** [sqlite3_back
3d640 75 70 5f 66 69 6e 69 73 68 28 29 5d 2e 0a 2a 2a up_finish()]..**
3d650 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 5b 55 .** See Also: [U
3d660 73 69 6e 67 20 74 68 65 20 53 51 4c 69 74 65 20 sing the SQLite
3d670 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 41 50 Online Backup AP
3d680 49 5d 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 I].*/.typedef st
3d690 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 61 63 ruct sqlite3_bac
3d6a0 6b 75 70 20 73 71 6c 69 74 65 33 5f 62 61 63 6b kup sqlite3_back
3d6b0 75 70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 up;../*.** CAPI3
3d6c0 52 45 46 3a 20 4f 6e 6c 69 6e 65 20 42 61 63 6b REF: Online Back
3d6d0 75 70 20 41 50 49 2e 0a 2a 2a 20 45 58 50 45 52 up API..** EXPER
3d6e0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
3d6f0 69 73 20 41 50 49 20 69 73 20 75 73 65 64 20 74 is API is used t
3d700 6f 20 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 o overwrite the
3d710 63 6f 6e 74 65 6e 74 73 20 6f 66 20 6f 6e 65 20 contents of one
3d720 64 61 74 61 62 61 73 65 20 77 69 74 68 20 74 68 database with th
3d730 61 74 0a 2a 2a 20 6f 66 20 61 6e 6f 74 68 65 72 at.** of another
3d740 2e 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 65 . It is useful e
3d750 69 74 68 65 72 20 66 6f 72 20 63 72 65 61 74 69 ither for creati
3d760 6e 67 20 62 61 63 6b 75 70 73 20 6f 66 20 64 61 ng backups of da
3d770 74 61 62 61 73 65 73 20 6f 72 0a 2a 2a 20 66 6f tabases or.** fo
3d780 72 20 63 6f 70 79 69 6e 67 20 69 6e 2d 6d 65 6d r copying in-mem
3d790 6f 72 79 20 64 61 74 61 62 61 73 65 73 20 74 6f ory databases to
3d7a0 20 6f 72 20 66 72 6f 6d 20 70 65 72 73 69 73 74 or from persist
3d7b0 65 6e 74 20 66 69 6c 65 73 2e 20 0a 2a 2a 0a 2a ent files. .**.*
3d7c0 2a 20 53 65 65 20 41 6c 73 6f 3a 20 5b 55 73 69 * See Also: [Usi
3d7d0 6e 67 20 74 68 65 20 53 51 4c 69 74 65 20 4f 6e ng the SQLite On
3d7e0 6c 69 6e 65 20 42 61 63 6b 75 70 20 41 50 49 5d line Backup API]
3d7f0 0a 2a 2a 0a 2a 2a 20 45 78 63 6c 75 73 69 76 65 .**.** Exclusive
3d800 20 61 63 63 65 73 73 20 69 73 20 72 65 71 75 69 access is requi
3d810 72 65 64 20 74 6f 20 74 68 65 20 64 65 73 74 69 red to the desti
3d820 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 nation database
3d830 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 75 72 61 for the .** dura
3d840 74 69 6f 6e 20 6f 66 20 74 68 65 20 6f 70 65 72 tion of the oper
3d850 61 74 69 6f 6e 2e 20 48 6f 77 65 76 65 72 20 74 ation. However t
3d860 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3d870 73 65 20 69 73 20 6f 6e 6c 79 0a 2a 2a 20 72 65 se is only.** re
3d880 61 64 2d 6c 6f 63 6b 65 64 20 77 68 69 6c 65 20 ad-locked while
3d890 69 74 20 69 73 20 61 63 74 75 61 6c 6c 79 20 62 it is actually b
3d8a0 65 69 6e 67 20 72 65 61 64 2c 20 69 74 20 69 73 eing read, it is
3d8b0 20 6e 6f 74 20 6c 6f 63 6b 65 64 0a 2a 2a 20 63 not locked.** c
3d8c0 6f 6e 74 69 6e 75 6f 75 73 6c 79 20 66 6f 72 20 ontinuously for
3d8d0 74 68 65 20 65 6e 74 69 72 65 20 6f 70 65 72 61 the entire opera
3d8e0 74 69 6f 6e 2e 20 54 68 75 73 2c 20 74 68 65 20 tion. Thus, the
3d8f0 62 61 63 6b 75 70 20 6d 61 79 20 62 65 0a 2a 2a backup may be.**
3d900 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 61 20 performed on a
3d910 6c 69 76 65 20 64 61 74 61 62 61 73 65 20 77 69 live database wi
3d920 74 68 6f 75 74 20 70 72 65 76 65 6e 74 69 6e 67 thout preventing
3d930 20 6f 74 68 65 72 20 75 73 65 72 73 20 66 72 6f other users fro
3d940 6d 0a 2a 2a 20 77 72 69 74 69 6e 67 20 74 6f 20 m.** writing to
3d950 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 the database for
3d960 20 61 6e 20 65 78 74 65 6e 64 65 64 20 70 65 72 an extended per
3d970 69 6f 64 20 6f 66 20 74 69 6d 65 2e 0a 2a 2a 20 iod of time..**
3d980 0a 2a 2a 20 54 6f 20 70 65 72 66 6f 72 6d 20 61 .** To perform a
3d990 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f backup operatio
3d9a0 6e 3a 20 0a 2a 2a 20 20 20 3c 6f 6c 3e 0a 2a 2a n: .** <ol>.**
3d9b0 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c 69 <li><b>sqli
3d9c0 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 te3_backup_init(
3d9d0 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 20 )</b> is called
3d9e0 6f 6e 63 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 once to initiali
3d9f0 7a 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ze the.**
3da00 20 20 62 61 63 6b 75 70 2c 20 0a 2a 2a 20 20 20 backup, .**
3da10 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 33 <li><b>sqlite3
3da20 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 3c 2f _backup_step()</
3da30 62 3e 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 b> is called one
3da40 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 or more times t
3da50 6f 20 74 72 61 6e 73 66 65 72 20 0a 2a 2a 20 20 o transfer .**
3da60 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61 20 the data
3da70 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 between the two
3da80 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 66 databases, and f
3da90 69 6e 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 3c 6c inally.** <l
3daa0 69 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 i><b>sqlite3_bac
3dab0 6b 75 70 5f 66 69 6e 69 73 68 28 29 3c 2f 62 3e kup_finish()</b>
3dac0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
3dad0 6c 65 61 73 65 20 61 6c 6c 20 72 65 73 6f 75 72 lease all resour
3dae0 63 65 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 ces .**
3daf0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
3db00 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 the backup opera
3db10 74 69 6f 6e 2e 20 0a 2a 2a 20 20 20 3c 2f 6f 6c tion. .** </ol
3db20 3e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c >.** There shoul
3db30 64 20 62 65 20 65 78 61 63 74 6c 79 20 6f 6e 65 d be exactly one
3db40 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
3db50 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3db60 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 73 75 63 for each.** suc
3db70 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
3db80 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 sqlite3_backup_i
3db90 6e 69 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e nit()..**.** <b>
3dba0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 sqlite3_backup_i
3dbb0 6e 69 74 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 nit()</b>.**.**
3dbc0 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 61 72 The first two ar
3dbd0 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20 74 guments passed t
3dbe0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 o [sqlite3_backu
3dbf0 70 5f 69 6e 69 74 28 29 5d 20 61 72 65 20 74 68 p_init()] are th
3dc00 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 e database.** ha
3dc10 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 ndle associated
3dc20 77 69 74 68 20 74 68 65 20 64 65 73 74 69 6e 61 with the destina
3dc30 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 61 6e tion database an
3dc40 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e d the database n
3dc50 61 6d 65 20 0a 2a 2a 20 75 73 65 64 20 74 6f 20 ame .** used to
3dc60 61 74 74 61 63 68 20 74 68 65 20 64 65 73 74 69 attach the desti
3dc70 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 nation database
3dc80 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 2e 20 54 to the handle. T
3dc90 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 he database name
3dca0 0a 2a 2a 20 69 73 20 22 6d 61 69 6e 22 20 66 6f .** is "main" fo
3dcb0 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 r the main datab
3dcc0 61 73 65 2c 20 22 74 65 6d 70 22 20 66 6f 72 20 ase, "temp" for
3dcd0 74 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 61 the temporary da
3dce0 74 61 62 61 73 65 2c 20 6f 72 0a 2a 2a 20 74 68 tabase, or.** th
3dcf0 65 20 6e 61 6d 65 20 73 70 65 63 69 66 69 65 64 e name specified
3dd00 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 as part of the
3dd10 5b 41 54 54 41 43 48 5d 20 73 74 61 74 65 6d 65 [ATTACH] stateme
3dd20 6e 74 20 69 66 20 74 68 65 20 64 65 73 74 69 6e nt if the destin
3dd30 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 6e 20 61 ation is.** an a
3dd40 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
3dd50 2e 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 . The third and
3dd60 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 fourth arguments
3dd70 20 70 61 73 73 65 64 20 74 6f 20 0a 2a 2a 20 73 passed to .** s
3dd80 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e qlite3_backup_in
3dd90 69 74 28 29 20 69 64 65 6e 74 69 66 79 20 74 68 it() identify th
3dda0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
3ddb0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 61 6e 64 20 64 ection].** and d
3ddc0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 75 73 65 atabase name use
3ddd0 64 0a 2a 2a 20 74 6f 20 61 63 63 65 73 73 20 74 d.** to access t
3dde0 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3ddf0 73 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 70 se. The values p
3de00 61 73 73 65 64 20 66 6f 72 20 74 68 65 20 73 6f assed for the so
3de10 75 72 63 65 20 61 6e 64 20 0a 2a 2a 20 64 65 73 urce and .** des
3de20 74 69 6e 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 tination [databa
3de30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 se connection] p
3de40 61 72 61 6d 65 74 65 72 73 20 6d 75 73 74 20 6e arameters must n
3de50 6f 74 20 62 65 20 74 68 65 20 73 61 6d 65 2e 0a ot be the same..
3de60 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f **.** If an erro
3de70 72 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 r occurs within
3de80 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 sqlite3_backup_i
3de90 6e 69 74 28 29 2c 20 74 68 65 6e 20 4e 55 4c 4c nit(), then NULL
3dea0 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 is returned.**
3deb0 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 and an error cod
3dec0 65 20 61 6e 64 20 65 72 72 6f 72 20 6d 65 73 73 e and error mess
3ded0 61 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f age written into
3dee0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
3def0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a 20 70 onnection] .** p
3df00 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
3df10 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 st argument. The
3df20 79 20 6d 61 79 20 62 65 20 72 65 74 72 69 65 76 y may be retriev
3df30 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 ed using the.**
3df40 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
3df50 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 ()], [sqlite3_er
3df60 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 rmsg()], and [sq
3df70 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
3df80 5d 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 ] functions..**
3df90 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20 73 75 Otherwise, if su
3dfa0 63 63 65 73 73 66 75 6c 2c 20 61 20 70 6f 69 6e ccessful, a poin
3dfb0 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 ter to an [sqlit
3dfc0 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 e3_backup] objec
3dfd0 74 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 t is.** returned
3dfe0 2e 20 54 68 69 73 20 70 6f 69 6e 74 65 72 20 6d . This pointer m
3dff0 61 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ay be used with
3e000 74 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b the sqlite3_back
3e010 75 70 5f 73 74 65 70 28 29 20 61 6e 64 0a 2a 2a up_step() and.**
3e020 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3e030 66 69 6e 69 73 68 28 29 20 66 75 6e 63 74 69 6f finish() functio
3e040 6e 73 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 ns to perform th
3e050 65 20 73 70 65 63 69 66 69 65 64 20 62 61 63 6b e specified back
3e060 75 70 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e up .** operation
3e070 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 ..**.** <b>sqlit
3e080 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3e090 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 46 75 6e 63 74 </b>.**.** Funct
3e0a0 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 ion [sqlite3_bac
3e0b0 6b 75 70 5f 73 74 65 70 28 29 5d 20 69 73 20 75 kup_step()] is u
3e0c0 73 65 64 20 74 6f 20 63 6f 70 79 20 75 70 20 74 sed to copy up t
3e0d0 6f 20 6e 50 61 67 65 20 70 61 67 65 73 20 62 65 o nPage pages be
3e0e0 74 77 65 65 6e 20 0a 2a 2a 20 74 68 65 20 73 6f tween .** the so
3e0f0 75 72 63 65 20 61 6e 64 20 64 65 73 74 69 6e 61 urce and destina
3e100 74 69 6f 6e 20 64 61 74 61 62 61 73 65 73 2c 20 tion databases,
3e110 77 68 65 72 65 20 6e 50 61 67 65 20 69 73 20 74 where nPage is t
3e120 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
3e130 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
3e140 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 73 eter passed to s
3e150 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3e160 65 70 28 29 2e 20 49 66 20 6e 50 61 67 65 20 69 ep(). If nPage i
3e170 73 20 61 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 s a negative.**
3e180 76 61 6c 75 65 2c 20 61 6c 6c 20 72 65 6d 61 69 value, all remai
3e190 6e 69 6e 67 20 73 6f 75 72 63 65 20 70 61 67 65 ning source page
3e1a0 73 20 61 72 65 20 63 6f 70 69 65 64 2e 20 49 66 s are copied. If
3e1b0 20 74 68 65 20 72 65 71 75 69 72 65 64 20 70 61 the required pa
3e1c0 67 65 73 20 61 72 65 20 0a 2a 2a 20 73 75 63 63 ges are .** succ
3e1d0 65 73 66 75 6c 6c 79 20 63 6f 70 69 65 64 2c 20 esfully copied,
3e1e0 62 75 74 20 74 68 65 72 65 20 61 72 65 20 73 74 but there are st
3e1f0 69 6c 6c 20 6d 6f 72 65 20 70 61 67 65 73 20 74 ill more pages t
3e200 6f 20 63 6f 70 79 20 62 65 66 6f 72 65 20 74 68 o copy before th
3e210 65 20 0a 2a 2a 20 62 61 63 6b 75 70 20 69 73 20 e .** backup is
3e220 63 6f 6d 70 6c 65 74 65 2c 20 69 74 20 72 65 74 complete, it ret
3e230 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
3e240 2e 20 49 66 20 6e 6f 20 65 72 72 6f 72 20 6f 63 . If no error oc
3e250 63 75 72 65 64 20 61 6e 64 20 74 68 65 72 65 20 cured and there
3e260 0a 2a 2a 20 61 72 65 20 6e 6f 20 6d 6f 72 65 20 .** are no more
3e270 70 61 67 65 73 20 74 6f 20 63 6f 70 79 2c 20 74 pages to copy, t
3e280 68 65 6e 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 hen [SQLITE_DONE
3e290 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 ] is returned. I
3e2a0 66 20 61 6e 20 65 72 72 6f 72 20 0a 2a 2a 20 6f f an error .** o
3e2b0 63 63 75 72 73 2c 20 74 68 65 6e 20 61 6e 20 53 ccurs, then an S
3e2c0 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65 QLite error code
3e2d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 41 73 is returned. As
3e2e0 20 77 65 6c 6c 20 61 73 20 5b 53 51 4c 49 54 45 well as [SQLITE
3e2f0 5f 4f 4b 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c _OK] and.** [SQL
3e300 49 54 45 5f 44 4f 4e 45 5d 2c 20 61 20 63 61 6c ITE_DONE], a cal
3e310 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 l to sqlite3_bac
3e320 6b 75 70 5f 73 74 65 70 28 29 20 6d 61 79 20 72 kup_step() may r
3e330 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 52 45 eturn [SQLITE_RE
3e340 41 44 4f 4e 4c 59 5d 2c 0a 2a 2a 20 5b 53 51 4c ADONLY],.** [SQL
3e350 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c ITE_NOMEM], [SQL
3e360 49 54 45 5f 42 55 53 59 5d 2c 20 5b 53 51 4c 49 ITE_BUSY], [SQLI
3e370 54 45 5f 4c 4f 43 4b 45 44 5d 2c 20 6f 72 20 61 TE_LOCKED], or a
3e380 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 n.** [SQLITE_IOE
3e390 52 52 5f 41 43 43 45 53 53 20 7c 20 53 51 4c 49 RR_ACCESS | SQLI
3e3a0 54 45 5f 49 4f 45 52 52 5f 58 58 58 5d 20 65 78 TE_IOERR_XXX] ex
3e3b0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
3e3c0 65 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c e..**.** As well
3e3d0 20 61 73 20 74 68 65 20 63 61 73 65 20 77 68 65 as the case whe
3e3e0 72 65 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 re the destinati
3e3f0 6f 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 on database file
3e400 20 77 61 73 20 6f 70 65 6e 65 64 20 66 6f 72 0a was opened for.
3e410 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 ** read-only acc
3e420 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 61 63 ess, sqlite3_bac
3e430 6b 75 70 5f 73 74 65 70 28 29 20 6d 61 79 20 72 kup_step() may r
3e440 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 52 45 eturn [SQLITE_RE
3e450 41 44 4f 4e 4c 59 5d 20 69 66 0a 2a 2a 20 74 68 ADONLY] if.** th
3e460 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 69 73 e destination is
3e470 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 an in-memory da
3e480 74 61 62 61 73 65 20 77 69 74 68 20 61 20 64 69 tabase with a di
3e490 66 66 65 72 65 6e 74 20 70 61 67 65 20 73 69 7a fferent page siz
3e4a0 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 6f e.** from the so
3e4b0 75 72 63 65 20 64 61 74 61 62 61 73 65 2e 0a 2a urce database..*
3e4c0 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f *.** If sqlite3_
3e4d0 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 61 backup_step() ca
3e4e0 6e 6e 6f 74 20 6f 62 74 61 69 6e 20 61 20 72 65 nnot obtain a re
3e4f0 71 75 69 72 65 64 20 66 69 6c 65 2d 73 79 73 74 quired file-syst
3e500 65 6d 20 6c 6f 63 6b 2c 20 74 68 65 6e 0a 2a 2a em lock, then.**
3e510 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 the [sqlite3_bu
3e520 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 sy_handler | bus
3e530 79 2d 68 61 6e 64 6c 65 72 20 66 75 6e 63 74 69 y-handler functi
3e540 6f 6e 5d 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 on].** is invoke
3e550 64 20 28 69 66 20 6f 6e 65 20 69 73 20 73 70 65 d (if one is spe
3e560 63 69 66 69 65 64 29 2e 20 49 66 20 74 68 65 20 cified). If the
3e570 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 .** busy-handler
3e580 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
3e590 6f 20 62 65 66 6f 72 65 20 74 68 65 20 6c 6f 63 o before the loc
3e5a0 6b 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2c 20 k is available,
3e5b0 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 then .** [SQLITE
3e5c0 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e _BUSY] is return
3e5d0 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 ed to the caller
3e5e0 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 . In this case t
3e5f0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 he call to.** sq
3e600 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3e610 70 28 29 20 63 61 6e 20 62 65 20 72 65 74 72 69 p() can be retri
3e620 65 64 20 6c 61 74 65 72 2e 20 49 66 20 74 68 65 ed later. If the
3e630 20 73 6f 75 72 63 65 0a 2a 2a 20 5b 64 61 74 61 source.** [data
3e640 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3e650 0a 2a 2a 20 69 73 20 62 65 69 6e 67 20 75 73 65 .** is being use
3e660 64 20 74 6f 20 77 72 69 74 65 20 74 6f 20 74 68 d to write to th
3e670 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 e source databas
3e680 65 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 62 e when sqlite3_b
3e690 61 63 6b 75 70 5f 73 74 65 70 28 29 0a 2a 2a 20 ackup_step().**
3e6a0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 is called, then
3e6b0 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 [SQLITE_LOCKED]
3e6c0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 is returned imme
3e6d0 64 69 61 74 65 6c 79 2e 20 41 67 61 69 6e 2c 20 diately. Again,
3e6e0 69 6e 20 74 68 69 73 0a 2a 2a 20 63 61 73 65 20 in this.** case
3e6f0 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 the call to sqli
3e700 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3e710 29 20 63 61 6e 20 62 65 20 72 65 74 72 69 65 64 ) can be retried
3e720 20 6c 61 74 65 72 20 6f 6e 2e 20 49 66 0a 2a 2a later on. If.**
3e730 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 [SQLITE_IOERR_A
3e740 43 43 45 53 53 20 7c 20 53 51 4c 49 54 45 5f 49 CCESS | SQLITE_I
3e750 4f 45 52 52 5f 58 58 58 5d 2c 20 5b 53 51 4c 49 OERR_XXX], [SQLI
3e760 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 6f 72 0a 2a 2a TE_NOMEM], or.**
3e770 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c [SQLITE_READONL
3e780 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 Y] is returned,
3e790 74 68 65 6e 20 0a 2a 2a 20 74 68 65 72 65 20 69 then .** there i
3e7a0 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 72 65 s no point in re
3e7b0 74 72 79 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 trying the call
3e7c0 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3e7d0 70 5f 73 74 65 70 28 29 2e 20 54 68 65 73 65 20 p_step(). These
3e7e0 0a 2a 2a 20 65 72 72 6f 72 73 20 61 72 65 20 63 .** errors are c
3e7f0 6f 6e 73 69 64 65 72 65 64 20 66 61 74 61 6c 2e onsidered fatal.
3e800 20 41 74 20 74 68 69 73 20 70 6f 69 6e 74 20 74 At this point t
3e810 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
3e820 75 73 74 20 61 63 63 65 70 74 20 0a 2a 2a 20 74 ust accept .** t
3e830 68 61 74 20 74 68 65 20 62 61 63 6b 75 70 20 6f hat the backup o
3e840 70 65 72 61 74 69 6f 6e 20 68 61 73 20 66 61 69 peration has fai
3e850 6c 65 64 20 61 6e 64 20 70 61 73 73 20 74 68 65 led and pass the
3e860 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f backup operatio
3e870 6e 20 68 61 6e 64 6c 65 20 0a 2a 2a 20 74 6f 20 n handle .** to
3e880 74 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b the sqlite3_back
3e890 75 70 5f 66 69 6e 69 73 68 28 29 20 74 6f 20 72 up_finish() to r
3e8a0 65 6c 65 61 73 65 20 61 73 73 6f 63 69 61 74 65 elease associate
3e8b0 64 20 72 65 73 6f 75 72 63 65 73 2e 0a 2a 2a 0a d resources..**.
3e8c0 2a 2a 20 46 6f 6c 6c 6f 77 69 6e 67 20 74 68 65 ** Following the
3e8d0 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 73 first call to s
3e8e0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3e8f0 65 70 28 29 2c 20 61 6e 20 65 78 63 6c 75 73 69 ep(), an exclusi
3e900 76 65 20 6c 6f 63 6b 20 69 73 0a 2a 2a 20 6f 62 ve lock is.** ob
3e910 74 61 69 6e 65 64 20 6f 6e 20 74 68 65 20 64 65 tained on the de
3e920 73 74 69 6e 61 74 69 6f 6e 20 66 69 6c 65 2e 20 stination file.
3e930 49 74 20 69 73 20 6e 6f 74 20 72 65 6c 65 61 73 It is not releas
3e940 65 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 ed until either
3e950 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3e960 75 70 5f 66 69 6e 69 73 68 28 29 20 69 73 20 63 up_finish() is c
3e970 61 6c 6c 65 64 20 6f 72 20 74 68 65 20 62 61 63 alled or the bac
3e980 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 kup operation is
3e990 20 63 6f 6d 70 6c 65 74 65 20 0a 2a 2a 20 61 6e complete .** an
3e9a0 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 d sqlite3_backup
3e9b0 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 73 20 _step() returns
3e9c0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 41 [SQLITE_DONE]. A
3e9d0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 65 61 63 dditionally, eac
3e9e0 68 20 74 69 6d 65 20 0a 2a 2a 20 61 20 63 61 6c h time .** a cal
3e9f0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 l to sqlite3_bac
3ea00 6b 75 70 5f 73 74 65 70 28 29 20 69 73 20 6d 61 kup_step() is ma
3ea10 64 65 20 61 20 5b 73 68 61 72 65 64 20 6c 6f 63 de a [shared loc
3ea20 6b 5d 20 69 73 20 6f 62 74 61 69 6e 65 64 20 6f k] is obtained o
3ea30 6e 0a 2a 2a 20 74 68 65 20 73 6f 75 72 63 65 20 n.** the source
3ea40 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 54 database file. T
3ea50 68 69 73 20 6c 6f 63 6b 20 69 73 20 72 65 6c 65 his lock is rele
3ea60 61 73 65 64 20 62 65 66 6f 72 65 20 74 68 65 0a ased before the.
3ea70 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ** sqlite3_backu
3ea80 70 5f 73 74 65 70 28 29 20 63 61 6c 6c 20 72 65 p_step() call re
3ea90 74 75 72 6e 73 2e 20 42 65 63 61 75 73 65 20 74 turns. Because t
3eaa0 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3eab0 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 6c 6f 63 se is not.** loc
3eac0 6b 65 64 20 62 65 74 77 65 65 6e 20 63 61 6c 6c ked between call
3ead0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 s to sqlite3_bac
3eae0 6b 75 70 5f 73 74 65 70 28 29 2c 20 69 74 20 6d kup_step(), it m
3eaf0 61 79 20 62 65 20 6d 6f 64 69 66 69 65 64 20 6d ay be modified m
3eb00 69 64 2d 77 61 79 0a 2a 2a 20 74 68 72 6f 75 67 id-way.** throug
3eb10 68 20 74 68 65 20 62 61 63 6b 75 70 20 70 72 6f h the backup pro
3eb20 63 65 64 75 72 65 2e 20 49 66 20 74 68 65 20 73 cedure. If the s
3eb30 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 69 ource database i
3eb40 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e s modified by an
3eb50 0a 2a 2a 20 65 78 74 65 72 6e 61 6c 20 70 72 6f .** external pro
3eb60 63 65 73 73 20 6f 72 20 76 69 61 20 61 20 64 61 cess or via a da
3eb70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3eb80 6e 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 n other than the
3eb90 20 6f 6e 65 20 62 65 69 6e 67 0a 2a 2a 20 75 73 one being.** us
3eba0 65 64 20 62 79 20 74 68 65 20 62 61 63 6b 75 70 ed by the backup
3ebb0 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 6e operation, then
3ebc0 20 74 68 65 20 62 61 63 6b 75 70 20 77 69 6c 6c the backup will
3ebd0 20 62 65 20 74 72 61 6e 73 70 61 72 65 6e 74 6c be transparentl
3ebe0 79 0a 2a 2a 20 72 65 73 74 61 72 74 65 64 20 62 y.** restarted b
3ebf0 79 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 y the next call
3ec00 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3ec10 70 5f 73 74 65 70 28 29 2e 20 49 66 20 74 68 65 p_step(). If the
3ec20 20 73 6f 75 72 63 65 20 0a 2a 2a 20 64 61 74 61 source .** data
3ec30 62 61 73 65 20 69 73 20 6d 6f 64 69 66 69 65 64 base is modified
3ec40 20 62 79 20 74 68 65 20 75 73 69 6e 67 20 74 68 by the using th
3ec50 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
3ec60 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 73 20 69 73 connection as is
3ec70 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 used.** by the
3ec80 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e backup operation
3ec90 2c 20 74 68 65 6e 20 74 68 65 20 62 61 63 6b 75 , then the backu
3eca0 70 20 64 61 74 61 62 61 73 65 20 69 73 20 74 72 p database is tr
3ecb0 61 6e 73 70 61 72 65 6e 74 6c 79 20 0a 2a 2a 20 ansparently .**
3ecc0 75 70 64 61 74 65 64 20 61 74 20 74 68 65 20 73 updated at the s
3ecd0 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ame time..**.**
3ece0 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 <b>sqlite3_backu
3ecf0 70 5f 66 69 6e 69 73 68 28 29 3c 2f 62 3e 0a 2a p_finish()</b>.*
3ed00 2a 0a 2a 2a 20 4f 6e 63 65 20 73 71 6c 69 74 65 *.** Once sqlite
3ed10 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3ed20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 has returned [SQ
3ed30 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 6f 72 20 77 LITE_DONE], or w
3ed40 68 65 6e 20 74 68 65 20 0a 2a 2a 20 61 70 70 6c hen the .** appl
3ed50 69 63 61 74 69 6f 6e 20 77 69 73 68 65 73 20 74 ication wishes t
3ed60 6f 20 61 62 61 6e 64 6f 6e 20 74 68 65 20 62 61 o abandon the ba
3ed70 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2c 20 ckup operation,
3ed80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 the [sqlite3_bac
3ed90 6b 75 70 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 73 kup].** object s
3eda0 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 hould be passed
3edb0 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3edc0 70 5f 66 69 6e 69 73 68 28 29 2e 20 54 68 69 73 p_finish(). This
3edd0 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a releases all.**
3ede0 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 resources assoc
3edf0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 62 iated with the b
3ee00 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e ackup operation.
3ee10 20 49 66 20 73 71 6c 69 74 65 33 5f 62 61 63 6b If sqlite3_back
3ee20 75 70 5f 73 74 65 70 28 29 0a 2a 2a 20 68 61 73 up_step().** has
3ee30 20 6e 6f 74 20 79 65 74 20 72 65 74 75 72 6e 65 not yet returne
3ee40 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c d [SQLITE_DONE],
3ee50 20 74 68 65 6e 20 61 6e 79 20 61 63 74 69 76 65 then any active
3ee60 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74 69 write-transacti
3ee70 6f 6e 20 6f 6e 20 74 68 65 0a 2a 2a 20 64 65 73 on on the.** des
3ee80 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 tination databas
3ee90 65 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b e is rolled back
3eea0 2e 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 . The [sqlite3_b
3eeb0 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 20 69 73 ackup] object is
3eec0 20 69 6e 76 61 6c 69 64 0a 2a 2a 20 61 6e 64 20 invalid.** and
3eed0 6d 61 79 20 6e 6f 74 20 62 65 20 75 73 65 64 20 may not be used
3eee0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c following a call
3eef0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3ef00 75 70 5f 66 69 6e 69 73 68 28 29 2e 0a 2a 2a 0a up_finish()..**.
3ef10 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 ** The value ret
3ef20 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
3ef30 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 69 _backup_finish i
3ef40 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 s [SQLITE_OK] if
3ef50 20 6e 6f 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 no error.** occ
3ef60 75 72 72 65 64 2c 20 72 65 67 61 72 64 6c 65 73 urred, regardles
3ef70 73 20 6f 72 20 77 68 65 74 68 65 72 20 6f 72 20 s or whether or
3ef80 6e 6f 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b not sqlite3_back
3ef90 75 70 5f 73 74 65 70 28 29 20 77 61 73 20 63 61 up_step() was ca
3efa0 6c 6c 65 64 0a 2a 2a 20 61 20 73 75 66 66 69 63 lled.** a suffic
3efb0 69 65 6e 74 20 6e 75 6d 62 65 72 20 6f 66 20 74 ient number of t
3efc0 69 6d 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 65 imes to complete
3efd0 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 the backup oper
3efe0 61 74 69 6f 6e 2e 20 4f 72 2c 20 69 66 0a 2a 2a ation. Or, if.**
3eff0 20 61 6e 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 an out-of-memor
3f000 79 20 63 6f 6e 64 69 74 69 6f 6e 20 6f 72 20 49 y condition or I
3f010 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 65 64 20 O error occured
3f020 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f during a call to
3f030 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3f040 75 70 5f 73 74 65 70 28 29 20 74 68 65 6e 20 5b up_step() then [
3f050 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 6f 72 SQLITE_NOMEM] or
3f060 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 an.** [SQLITE_I
3f070 4f 45 52 52 5f 41 43 43 45 53 53 20 7c 20 53 51 OERR_ACCESS | SQ
3f080 4c 49 54 45 5f 49 4f 45 52 52 5f 58 58 58 5d 20 LITE_IOERR_XXX]
3f090 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 69 73 error code.** is
3f0a0 20 72 65 74 75 72 6e 65 64 2e 20 49 6e 20 74 68 returned. In th
3f0b0 69 73 20 63 61 73 65 20 74 68 65 20 65 72 72 6f is case the erro
3f0c0 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 r code and an er
3f0d0 72 6f 72 20 6d 65 73 73 61 67 65 20 61 72 65 0a ror message are.
3f0e0 2a 2a 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68 ** written to th
3f0f0 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 5b 64 e destination [d
3f100 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3f110 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 74 on]..**.** A ret
3f120 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 urn of [SQLITE_B
3f130 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
3f140 4c 4f 43 4b 45 44 5d 20 66 72 6f 6d 20 73 71 6c LOCKED] from sql
3f150 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3f160 28 29 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 () is.** not a p
3f170 65 72 6d 61 6e 65 6e 74 20 65 72 72 6f 72 20 61 ermanent error a
3f180 6e 64 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 nd does not affe
3f190 63 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ct the return va
3f1a0 6c 75 65 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 lue of.** sqlite
3f1b0 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
3f1c0 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 )..**.** <b>sqli
3f1d0 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 te3_backup_remai
3f1e0 6e 69 6e 67 28 29 2c 20 73 71 6c 69 74 65 33 5f ning(), sqlite3_
3f1f0 62 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 backup_pagecount
3f200 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 ()</b>.**.** Eac
3f210 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 h call to sqlite
3f220 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3f230 73 65 74 73 20 74 77 6f 20 76 61 6c 75 65 73 20 sets two values
3f240 73 74 6f 72 65 64 20 69 6e 74 65 72 6e 61 6c 6c stored internall
3f250 79 0a 2a 2a 20 62 79 20 61 6e 20 5b 73 71 6c 69 y.** by an [sqli
3f260 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 te3_backup] obje
3f270 63 74 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f ct. The number o
3f280 66 20 70 61 67 65 73 20 73 74 69 6c 6c 20 74 6f f pages still to
3f290 20 62 65 20 62 61 63 6b 65 64 0a 2a 2a 20 75 70 be backed.** up
3f2a0 2c 20 77 68 69 63 68 20 6d 61 79 20 62 65 20 71 , which may be q
3f2b0 75 65 72 69 65 64 20 62 79 20 73 71 6c 69 74 65 ueried by sqlite
3f2c0 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e 69 3_backup_remaini
3f2d0 6e 67 28 29 2c 20 61 6e 64 20 74 68 65 20 74 6f ng(), and the to
3f2e0 74 61 6c 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 tal.** number of
3f2f0 20 70 61 67 65 73 20 69 6e 20 74 68 65 20 73 6f pages in the so
3f300 75 72 63 65 20 64 61 74 61 62 61 73 65 20 66 69 urce database fi
3f310 6c 65 2c 20 77 68 69 63 68 20 6d 61 79 20 62 65 le, which may be
3f320 20 71 75 65 72 69 65 64 20 62 79 0a 2a 2a 20 73 queried by.** s
3f330 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 qlite3_backup_pa
3f340 67 65 63 6f 75 6e 74 28 29 2e 0a 2a 2a 0a 2a 2a gecount()..**.**
3f350 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 The values retu
3f360 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 66 75 rned by these fu
3f370 6e 63 74 69 6f 6e 73 20 61 72 65 20 6f 6e 6c 79 nctions are only
3f380 20 75 70 64 61 74 65 64 20 62 79 0a 2a 2a 20 73 updated by.** s
3f390 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3f3a0 65 70 28 29 2e 20 49 66 20 74 68 65 20 73 6f 75 ep(). If the sou
3f3b0 72 63 65 20 64 61 74 61 62 61 73 65 20 69 73 20 rce database is
3f3c0 6d 6f 64 69 66 69 65 64 20 64 75 72 69 6e 67 20 modified during
3f3d0 61 20 62 61 63 6b 75 70 0a 2a 2a 20 6f 70 65 72 a backup.** oper
3f3e0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ation, then the
3f3f0 76 61 6c 75 65 73 20 61 72 65 20 6e 6f 74 20 75 values are not u
3f400 70 64 61 74 65 64 20 74 6f 20 61 63 63 6f 75 6e pdated to accoun
3f410 74 20 66 6f 72 20 61 6e 79 20 65 78 74 72 61 0a t for any extra.
3f420 2a 2a 20 70 61 67 65 73 20 74 68 61 74 20 6e 65 ** pages that ne
3f430 65 64 20 74 6f 20 62 65 20 75 70 64 61 74 65 64 ed to be updated
3f440 20 6f 72 20 74 68 65 20 73 69 7a 65 20 6f 66 20 or the size of
3f450 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 the source datab
3f460 61 73 65 20 66 69 6c 65 0a 2a 2a 20 63 68 61 6e ase file.** chan
3f470 67 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 43 ging..**.** <b>C
3f480 6f 6e 63 75 72 72 65 6e 74 20 55 73 61 67 65 20 oncurrent Usage
3f490 6f 66 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 of Database Hand
3f4a0 6c 65 73 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 les</b>.**.** Th
3f4b0 65 20 73 6f 75 72 63 65 20 5b 64 61 74 61 62 61 e source [databa
3f4c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6d se connection] m
3f4d0 61 79 20 62 65 20 75 73 65 64 20 62 79 20 74 68 ay be used by th
3f4e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 6f e application fo
3f4f0 72 20 6f 74 68 65 72 0a 2a 2a 20 70 75 72 70 6f r other.** purpo
3f500 73 65 73 20 77 68 69 6c 65 20 61 20 62 61 63 6b ses while a back
3f510 75 70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 up operation is
3f520 75 6e 64 65 72 77 61 79 20 6f 72 20 62 65 69 6e underway or bein
3f530 67 20 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a g initialized..*
3f540 2a 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 * If SQLite is c
3f550 6f 6d 70 69 6c 65 64 20 61 6e 64 20 63 6f 6e 66 ompiled and conf
3f560 69 67 75 72 65 64 20 74 6f 20 73 75 70 70 6f 72 igured to suppor
3f570 74 20 74 68 72 65 61 64 73 61 66 65 20 64 61 74 t threadsafe dat
3f580 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
3f590 69 6f 6e 73 2c 20 74 68 65 6e 20 74 68 65 20 73 ions, then the s
3f5a0 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 63 ource database c
3f5b0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 61 79 20 62 65 onnection may be
3f5c0 20 75 73 65 64 20 63 6f 6e 63 75 72 72 65 6e 74 used concurrent
3f5d0 6c 79 0a 2a 2a 20 66 72 6f 6d 20 77 69 74 68 69 ly.** from withi
3f5e0 6e 20 6f 74 68 65 72 20 74 68 72 65 61 64 73 2e n other threads.
3f5f0 0a 2a 2a 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 .**.** However,
3f600 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
3f610 6d 75 73 74 20 67 75 61 72 61 6e 74 65 65 20 74 must guarantee t
3f620 68 61 74 20 74 68 65 20 64 65 73 74 69 6e 61 74 hat the destinat
3f630 69 6f 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ion database.**
3f640 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c connection handl
3f650 65 20 69 73 20 6e 6f 74 20 70 61 73 73 65 64 20 e is not passed
3f660 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 41 50 49 to any other API
3f670 20 28 62 79 20 61 6e 79 20 74 68 72 65 61 64 29 (by any thread)
3f680 20 61 66 74 65 72 20 0a 2a 2a 20 73 71 6c 69 74 after .** sqlit
3f690 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 e3_backup_init()
3f6a0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 20 62 is called and b
3f6b0 65 66 6f 72 65 20 74 68 65 20 63 6f 72 72 65 73 efore the corres
3f6c0 70 6f 6e 64 69 6e 67 20 63 61 6c 6c 20 74 6f 0a ponding call to.
3f6d0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ** sqlite3_backu
3f6e0 70 5f 66 69 6e 69 73 68 28 29 2e 20 55 6e 66 6f p_finish(). Unfo
3f6f0 72 74 75 6e 61 74 65 6c 79 20 53 51 4c 69 74 65 rtunately SQLite
3f700 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e does not curren
3f710 74 6c 79 20 63 68 65 63 6b 0a 2a 2a 20 66 6f 72 tly check.** for
3f720 20 74 68 69 73 2c 20 69 66 20 74 68 65 20 61 70 this, if the ap
3f730 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 75 plication does u
3f740 73 65 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 se the destinati
3f750 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
3f760 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 66 6f 72 20 nection].** for
3f770 73 6f 6d 65 20 6f 74 68 65 72 20 70 75 72 70 6f some other purpo
3f780 73 65 20 64 75 72 69 6e 67 20 61 20 62 61 63 6b se during a back
3f790 75 70 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 up operation, th
3f7a0 69 6e 67 73 20 6d 61 79 20 61 70 70 65 61 72 20 ings may appear
3f7b0 74 6f 0a 2a 2a 20 77 6f 72 6b 20 63 6f 72 72 65 to.** work corre
3f7c0 63 74 6c 79 20 62 75 74 20 69 6e 20 66 61 63 74 ctly but in fact
3f7d0 20 62 65 20 73 75 62 74 6c 79 20 6d 61 6c 66 75 be subtly malfu
3f7e0 6e 63 74 69 6f 6e 69 6e 67 2e 20 20 55 73 65 20 nctioning. Use
3f7f0 6f 66 20 74 68 65 0a 2a 2a 20 64 65 73 74 69 6e of the.** destin
3f800 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 63 ation database c
3f810 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 onnection while
3f820 61 20 62 61 63 6b 75 70 20 69 73 20 69 6e 20 70 a backup is in p
3f830 72 6f 67 72 65 73 73 20 6d 69 67 68 74 0a 2a 2a rogress might.**
3f840 20 61 6c 73 6f 20 63 61 75 73 65 20 61 20 6d 75 also cause a mu
3f850 74 65 78 20 64 65 61 64 6c 6f 63 6b 2e 0a 2a 2a tex deadlock..**
3f860 0a 2a 2a 20 46 75 72 74 68 65 72 6d 6f 72 65 2c .** Furthermore,
3f870 20 69 66 20 72 75 6e 6e 69 6e 67 20 69 6e 20 5b if running in [
3f880 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 shared cache mod
3f890 65 5d 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 e], the applicat
3f8a0 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 67 75 61 72 ion must.** guar
3f8b0 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 73 antee that the s
3f8c0 68 61 72 65 64 20 63 61 63 68 65 20 75 73 65 64 hared cache used
3f8d0 20 62 79 20 74 68 65 20 64 65 73 74 69 6e 61 74 by the destinat
3f8e0 69 6f 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ion database.**
3f8f0 69 73 20 6e 6f 74 20 61 63 63 65 73 73 65 64 20 is not accessed
3f900 77 68 69 6c 65 20 74 68 65 20 62 61 63 6b 75 70 while the backup
3f910 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 49 6e 20 is running. In
3f920 70 72 61 63 74 69 63 65 20 74 68 69 73 20 6d 65 practice this me
3f930 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ans.** that the
3f940 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
3f950 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
3f960 74 68 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 the file-system
3f970 66 69 6c 65 20 62 65 69 6e 67 20 0a 2a 2a 20 62 file being .** b
3f980 61 63 6b 65 64 20 75 70 20 74 6f 20 69 73 20 6e acked up to is n
3f990 6f 74 20 61 63 63 65 73 73 65 64 20 62 79 20 61 ot accessed by a
3f9a0 6e 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 ny connection wi
3f9b0 74 68 69 6e 20 74 68 65 20 70 72 6f 63 65 73 73 thin the process
3f9c0 2c 0a 2a 2a 20 6e 6f 74 20 6a 75 73 74 20 74 68 ,.** not just th
3f9d0 65 20 73 70 65 63 69 66 69 63 20 63 6f 6e 6e 65 e specific conne
3f9e0 63 74 69 6f 6e 20 74 68 61 74 20 77 61 73 20 70 ction that was p
3f9f0 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 assed to sqlite3
3fa00 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2e 0a _backup_init()..
3fa10 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
3fa20 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 e3_backup] objec
3fa30 74 20 69 74 73 65 6c 66 20 69 73 20 70 61 72 74 t itself is part
3fa40 69 61 6c 6c 79 20 74 68 72 65 61 64 73 61 66 65 ially threadsafe
3fa50 2e 20 4d 75 6c 74 69 70 6c 65 20 0a 2a 2a 20 74 . Multiple .** t
3fa60 68 72 65 61 64 73 20 6d 61 79 20 73 61 66 65 6c hreads may safel
3fa70 79 20 6d 61 6b 65 20 6d 75 6c 74 69 70 6c 65 20 y make multiple
3fa80 63 6f 6e 63 75 72 72 65 6e 74 20 63 61 6c 6c 73 concurrent calls
3fa90 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3faa0 75 70 5f 73 74 65 70 28 29 2e 0a 2a 2a 20 48 6f up_step()..** Ho
3fab0 77 65 76 65 72 2c 20 74 68 65 20 73 71 6c 69 74 wever, the sqlit
3fac0 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e e3_backup_remain
3fad0 69 6e 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ing() and sqlite
3fae0 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 3_backup_pagecou
3faf0 6e 74 28 29 0a 2a 2a 20 41 50 49 73 20 61 72 65 nt().** APIs are
3fb00 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 73 70 not strictly sp
3fb10 65 61 6b 69 6e 67 20 74 68 72 65 61 64 73 61 66 eaking threadsaf
3fb20 65 2e 20 49 66 20 74 68 65 79 20 61 72 65 20 69 e. If they are i
3fb30 6e 76 6f 6b 65 64 20 61 74 20 74 68 65 0a 2a 2a nvoked at the.**
3fb40 20 73 61 6d 65 20 74 69 6d 65 20 61 73 20 61 6e same time as an
3fb50 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 other thread is
3fb60 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 invoking sqlite3
3fb70 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 69 _backup_step() i
3fb80 74 20 69 73 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 t is.** possible
3fb90 20 74 68 61 74 20 74 68 65 79 20 72 65 74 75 72 that they retur
3fba0 6e 20 69 6e 76 61 6c 69 64 20 76 61 6c 75 65 73 n invalid values
3fbb0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
3fbc0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a sqlite3_backup *
3fbd0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 sqlite3_backup_i
3fbe0 6e 69 74 28 0a 20 20 73 71 6c 69 74 65 33 20 2a nit(. sqlite3 *
3fbf0 70 44 65 73 74 2c 20 20 20 20 20 20 20 20 20 20 pDest,
3fc00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3fc10 20 44 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 Destination dat
3fc20 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
3fc30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 const char *zD
3fc40 65 73 74 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 estName,
3fc50 20 20 20 20 20 20 20 20 20 2f 2a 20 44 65 73 74 /* Dest
3fc60 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 ination database
3fc70 20 6e 61 6d 65 20 2a 2f 0a 20 20 73 71 6c 69 74 name */. sqlit
3fc80 65 33 20 2a 70 53 6f 75 72 63 65 2c 20 20 20 20 e3 *pSource,
3fc90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fca0 20 20 2f 2a 20 53 6f 75 72 63 65 20 64 61 74 61 /* Source data
3fcb0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
3fcc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 6f const char *zSo
3fcd0 75 72 63 65 4e 61 6d 65 20 20 20 20 20 20 20 20 urceName
3fce0 20 20 20 20 20 20 20 20 2f 2a 20 53 6f 75 72 63 /* Sourc
3fcf0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 e database name
3fd00 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
3fd10 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 63 int sqlite3_bac
3fd20 6b 75 70 5f 73 74 65 70 28 73 71 6c 69 74 65 33 kup_step(sqlite3
3fd30 5f 62 61 63 6b 75 70 20 2a 70 2c 20 69 6e 74 20 _backup *p, int
3fd40 6e 50 61 67 65 29 3b 0a 53 51 4c 49 54 45 5f 41 nPage);.SQLITE_A
3fd50 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
3fd60 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 73 71 6c ackup_finish(sql
3fd70 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 29 3b ite3_backup *p);
3fd80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
3fd90 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 sqlite3_backup_r
3fda0 65 6d 61 69 6e 69 6e 67 28 73 71 6c 69 74 65 33 emaining(sqlite3
3fdb0 5f 62 61 63 6b 75 70 20 2a 70 29 3b 0a 53 51 4c _backup *p);.SQL
3fdc0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
3fdd0 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 te3_backup_pagec
3fde0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 62 61 63 ount(sqlite3_bac
3fdf0 6b 75 70 20 2a 70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 kup *p);../*.**
3fe00 43 41 50 49 33 52 45 46 3a 20 55 6e 6c 6f 63 6b CAPI3REF: Unlock
3fe10 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 0a 2a 2a Notification.**
3fe20 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
3fe30 0a 2a 2a 20 57 68 65 6e 20 72 75 6e 6e 69 6e 67 .** When running
3fe40 20 69 6e 20 73 68 61 72 65 64 2d 63 61 63 68 65 in shared-cache
3fe50 20 6d 6f 64 65 2c 20 61 20 64 61 74 61 62 61 73 mode, a databas
3fe60 65 20 6f 70 65 72 61 74 69 6f 6e 20 6d 61 79 20 e operation may
3fe70 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 61 6e 20 fail with.** an
3fe80 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 [SQLITE_LOCKED]
3fe90 65 72 72 6f 72 20 69 66 20 74 68 65 20 72 65 71 error if the req
3fea0 75 69 72 65 64 20 6c 6f 63 6b 73 20 6f 6e 20 74 uired locks on t
3feb0 68 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 he shared-cache
3fec0 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c or.** individual
3fed0 20 74 61 62 6c 65 73 20 77 69 74 68 69 6e 20 74 tables within t
3fee0 68 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 he shared-cache
3fef0 63 61 6e 6e 6f 74 20 62 65 20 6f 62 74 61 69 6e cannot be obtain
3ff00 65 64 2e 20 53 65 65 0a 2a 2a 20 5b 53 51 4c 69 ed. See.** [SQLi
3ff10 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 te Shared-Cache
3ff20 4d 6f 64 65 5d 20 66 6f 72 20 61 20 64 65 73 63 Mode] for a desc
3ff30 72 69 70 74 69 6f 6e 20 6f 66 20 73 68 61 72 65 ription of share
3ff40 64 2d 63 61 63 68 65 20 6c 6f 63 6b 69 6e 67 2e d-cache locking.
3ff50 20 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 .** This API ma
3ff60 79 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 67 y be used to reg
3ff70 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61 63 6b ister a callback
3ff80 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
3ff90 6c 20 69 6e 76 6f 6b 65 20 0a 2a 2a 20 77 68 65 l invoke .** whe
3ffa0 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e n the connection
3ffb0 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64 69 currently holdi
3ffc0 6e 67 20 74 68 65 20 72 65 71 75 69 72 65 64 20 ng the required
3ffd0 6c 6f 63 6b 20 72 65 6c 69 6e 71 75 69 73 68 65 lock relinquishe
3ffe0 73 20 69 74 2e 0a 2a 2a 20 54 68 69 73 20 41 50 s it..** This AP
3fff0 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 I is only availa
40000 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 ble if the libra
40010 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 ry was compiled
40020 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
40030 49 54 45 5f 45 4e 41 42 4c 45 5f 55 4e 4c 4f 43 ITE_ENABLE_UNLOC
40040 4b 5f 4e 4f 54 49 46 59 5d 20 43 2d 70 72 65 70 K_NOTIFY] C-prep
40050 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 rocessor symbol
40060 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 defined..**.** S
40070 65 65 20 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 ee Also: [Using
40080 74 68 65 20 53 51 4c 69 74 65 20 55 6e 6c 6f 63 the SQLite Unloc
40090 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 46 k Notification F
400a0 65 61 74 75 72 65 5d 2e 0a 2a 2a 0a 2a 2a 20 53 eature]..**.** S
400b0 68 61 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b hared-cache lock
400c0 73 20 61 72 65 20 72 65 6c 65 61 73 65 64 20 77 s are released w
400d0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 hen a database c
400e0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f 6e 63 6c 75 onnection conclu
400f0 64 65 73 0a 2a 2a 20 69 74 73 20 63 75 72 72 65 des.** its curre
40100 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 nt transaction,
40110 65 69 74 68 65 72 20 62 79 20 63 6f 6d 6d 69 74 either by commit
40120 74 69 6e 67 20 69 74 20 6f 72 20 72 6f 6c 6c 69 ting it or rolli
40130 6e 67 20 69 74 20 62 61 63 6b 2e 20 0a 2a 2a 0a ng it back. .**.
40140 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 6e 65 63 ** When a connec
40150 74 69 6f 6e 20 28 6b 6e 6f 77 6e 20 61 73 20 74 tion (known as t
40160 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 he blocked conne
40170 63 74 69 6f 6e 29 20 66 61 69 6c 73 20 74 6f 20 ction) fails to
40180 6f 62 74 61 69 6e 20 61 0a 2a 2a 20 73 68 61 72 obtain a.** shar
40190 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b 20 61 6e ed-cache lock an
401a0 64 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 d SQLITE_LOCKED
401b0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 is returned to t
401c0 68 65 20 63 61 6c 6c 65 72 2c 20 74 68 65 0a 2a he caller, the.*
401d0 2a 20 69 64 65 6e 74 69 74 79 20 6f 66 20 74 68 * identity of th
401e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
401f0 63 74 69 6f 6e 20 28 74 68 65 20 62 6c 6f 63 6b ction (the block
40200 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 29 20 ing connection)
40210 74 68 61 74 0a 2a 2a 20 68 61 73 20 6c 6f 63 6b that.** has lock
40220 65 64 20 74 68 65 20 72 65 71 75 69 72 65 64 20 ed the required
40230 72 65 73 6f 75 72 63 65 20 69 73 20 73 74 6f 72 resource is stor
40240 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 41 ed internally. A
40250 66 74 65 72 20 61 6e 20 0a 2a 2a 20 61 70 70 6c fter an .** appl
40260 69 63 61 74 69 6f 6e 20 72 65 63 65 69 76 65 73 ication receives
40270 20 61 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 an SQLITE_LOCKE
40280 44 20 65 72 72 6f 72 2c 20 69 74 20 6d 61 79 20 D error, it may
40290 63 61 6c 6c 20 74 68 65 0a 2a 2a 20 73 71 6c 69 call the.** sqli
402a0 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 te3_unlock_notif
402b0 79 28 29 20 6d 65 74 68 6f 64 20 77 69 74 68 20 y() method with
402c0 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e the blocked conn
402d0 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 61 73 ection handle as
402e0 20 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61 .** the first a
402f0 72 67 75 6d 65 6e 74 20 74 6f 20 72 65 67 69 73 rgument to regis
40300 74 65 72 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 ter for a callba
40310 63 6b 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 ck that will be
40320 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 invoked.** when
40330 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e the blocking con
40340 6e 65 63 74 69 6f 6e 73 20 63 75 72 72 65 6e 74 nections current
40350 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
40360 63 6f 6e 63 6c 75 64 65 64 2e 20 54 68 65 0a 2a concluded. The.*
40370 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e * callback is in
40380 76 6f 6b 65 64 20 66 72 6f 6d 20 77 69 74 68 69 voked from withi
40390 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 n the [sqlite3_s
403a0 74 65 70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 tep] or [sqlite3
403b0 5f 63 6c 6f 73 65 5d 0a 2a 2a 20 63 61 6c 6c 20 _close].** call
403c0 74 68 61 74 20 63 6f 6e 63 6c 75 64 65 73 20 74 that concludes t
403d0 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e he blocking conn
403e0 65 63 74 69 6f 6e 73 20 74 72 61 6e 73 61 63 74 ections transact
403f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 ion..**.** If sq
40400 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 lite3_unlock_not
40410 69 66 79 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ify() is called
40420 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 in a multi-threa
40430 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c ded application,
40440 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 63 .** there is a c
40450 68 61 6e 63 65 20 74 68 61 74 20 74 68 65 20 62 hance that the b
40460 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 locking connecti
40470 6f 6e 20 77 69 6c 6c 20 68 61 76 65 20 61 6c 72 on will have alr
40480 65 61 64 79 0a 2a 2a 20 63 6f 6e 63 6c 75 64 65 eady.** conclude
40490 64 20 69 74 73 20 74 72 61 6e 73 61 63 74 69 6f d its transactio
404a0 6e 20 62 79 20 74 68 65 20 74 69 6d 65 20 73 71 n by the time sq
404b0 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 lite3_unlock_not
404c0 69 66 79 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ify() is invoked
404d0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 68 61 70 ..** If this hap
404e0 70 65 6e 73 2c 20 74 68 65 6e 20 74 68 65 20 73 pens, then the s
404f0 70 65 63 69 66 69 65 64 20 63 61 6c 6c 62 61 63 pecified callbac
40500 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6d 6d k is invoked imm
40510 65 64 69 61 74 65 6c 79 2c 0a 2a 2a 20 66 72 6f ediately,.** fro
40520 6d 20 77 69 74 68 69 6e 20 74 68 65 20 63 61 6c m within the cal
40530 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 6e 6c l to sqlite3_unl
40540 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 2e 0a 2a 2a ock_notify()..**
40550 0a 2a 2a 20 49 66 20 74 68 65 20 62 6c 6f 63 6b .** If the block
40560 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 ed connection is
40570 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 6f attempting to o
40580 62 74 61 69 6e 20 61 20 77 72 69 74 65 2d 6c 6f btain a write-lo
40590 63 6b 20 6f 6e 20 61 0a 2a 2a 20 73 68 61 72 65 ck on a.** share
405a0 64 2d 63 61 63 68 65 20 74 61 62 6c 65 2c 20 61 d-cache table, a
405b0 6e 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 nd more than one
405c0 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f other connectio
405d0 6e 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64 n currently hold
405e0 73 0a 2a 2a 20 61 20 72 65 61 64 2d 6c 6f 63 6b s.** a read-lock
405f0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 74 61 62 on the same tab
40600 6c 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 le, then SQLite
40610 61 72 62 69 74 72 61 72 69 6c 79 20 73 65 6c 65 arbitrarily sele
40620 63 74 73 20 6f 6e 65 20 6f 66 20 0a 2a 2a 20 74 cts one of .** t
40630 68 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 he other connect
40640 69 6f 6e 73 20 74 6f 20 75 73 65 20 61 73 20 74 ions to use as t
40650 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e he blocking conn
40660 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 ection..**.** Th
40670 65 72 65 20 6d 61 79 20 62 65 20 61 74 20 6d 6f ere may be at mo
40680 73 74 20 6f 6e 65 20 75 6e 6c 6f 63 6b 2d 6e 6f st one unlock-no
40690 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 tify callback re
406a0 67 69 73 74 65 72 65 64 20 62 79 20 61 20 0a 2a gistered by a .*
406b0 2a 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 * blocked connec
406c0 74 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 65 33 tion. If sqlite3
406d0 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 _unlock_notify()
406e0 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 is called when
406f0 74 68 65 0a 2a 2a 20 62 6c 6f 63 6b 65 64 20 63 the.** blocked c
40700 6f 6e 6e 65 63 74 69 6f 6e 20 61 6c 72 65 61 64 onnection alread
40710 79 20 68 61 73 20 61 20 72 65 67 69 73 74 65 72 y has a register
40720 65 64 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 ed unlock-notify
40730 20 63 61 6c 6c 62 61 63 6b 2c 0a 2a 2a 20 74 68 callback,.** th
40740 65 6e 20 74 68 65 20 6e 65 77 20 63 61 6c 6c 62 en the new callb
40750 61 63 6b 20 72 65 70 6c 61 63 65 73 20 74 68 65 ack replaces the
40760 20 6f 6c 64 2e 20 49 66 20 73 71 6c 69 74 65 33 old. If sqlite3
40770 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 _unlock_notify()
40780 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 69 is.** called wi
40790 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
407a0 72 20 61 73 20 69 74 73 20 73 65 63 6f 6e 64 20 r as its second
407b0 61 72 67 75 6d 65 6e 74 2c 20 74 68 65 6e 20 61 argument, then a
407c0 6e 79 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 75 ny existing.** u
407d0 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c nlock-notify cal
407e0 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c lback is cancell
407f0 65 64 2e 20 54 68 65 20 62 6c 6f 63 6b 65 64 20 ed. The blocked
40800 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 0a 2a 2a 20 connections .**
40810 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 unlock-notify ca
40820 6c 6c 62 61 63 6b 20 6d 61 79 20 61 6c 73 6f 20 llback may also
40830 62 65 20 63 61 6e 63 65 6c 65 64 20 62 79 20 63 be canceled by c
40840 6c 6f 73 69 6e 67 20 74 68 65 20 62 6c 6f 63 6b losing the block
40850 65 64 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e ed.** connection
40860 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
40870 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 close()]..**.**
40880 54 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 The unlock-notif
40890 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f y callback is no
408a0 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 49 66 20 t reentrant. If
408b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 an application i
408c0 6e 76 6f 6b 65 73 0a 2a 2a 20 61 6e 79 20 73 71 nvokes.** any sq
408d0 6c 69 74 65 33 5f 78 78 78 20 41 50 49 20 66 75 lite3_xxx API fu
408e0 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 77 69 74 nctions from wit
408f0 68 69 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f hin an unlock-no
40900 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 2c 20 61 tify callback, a
40910 0a 2a 2a 20 63 72 61 73 68 20 6f 72 20 64 65 61 .** crash or dea
40920 64 6c 6f 63 6b 20 6d 61 79 20 62 65 20 74 68 65 dlock may be the
40930 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 55 result..**.** U
40940 6e 6c 65 73 73 20 64 65 61 64 6c 6f 63 6b 20 69 nless deadlock i
40950 73 20 64 65 74 65 63 74 65 64 20 28 73 65 65 20 s detected (see
40960 62 65 6c 6f 77 29 2c 20 73 71 6c 69 74 65 33 5f below), sqlite3_
40970 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
40980 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e always.** return
40990 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a s SQLITE_OK..**.
409a0 2a 2a 20 3c 62 3e 43 61 6c 6c 62 61 63 6b 20 49 ** <b>Callback I
409b0 6e 76 6f 63 61 74 69 6f 6e 20 44 65 74 61 69 6c nvocation Detail
409c0 73 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e s</b>.**.** When
409d0 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 an unlock-notif
409e0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 72 65 y callback is re
409f0 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 61 70 gistered, the ap
40a00 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 plication provid
40a10 65 73 20 61 20 0a 2a 2a 20 73 69 6e 67 6c 65 20 es a .** single
40a20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 74 68 void* pointer th
40a30 61 74 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 at is passed to
40a40 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 68 65 the callback whe
40a50 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e n it is invoked.
40a60 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
40a70 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 signature of th
40a80 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
40a90 69 6f 6e 20 61 6c 6c 6f 77 73 20 53 51 4c 69 74 ion allows SQLit
40aa0 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 69 74 20 e to pass.** it
40ab0 61 6e 20 61 72 72 61 79 20 6f 66 20 76 6f 69 64 an array of void
40ac0 2a 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 * context pointe
40ad0 72 73 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 rs. The first ar
40ae0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f gument passed to
40af0 0a 2a 2a 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f .** an unlock-no
40b00 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 tify callback is
40b10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
40b20 20 61 72 72 61 79 20 6f 66 20 76 6f 69 64 2a 20 array of void*
40b30 70 6f 69 6e 74 65 72 73 2c 0a 2a 2a 20 61 6e 64 pointers,.** and
40b40 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 the second is t
40b50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6e 74 he number of ent
40b60 72 69 65 73 20 69 6e 20 74 68 65 20 61 72 72 61 ries in the arra
40b70 79 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 y..**.** When a
40b80 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 blocking connect
40b90 69 6f 6e 73 20 74 72 61 6e 73 61 63 74 69 6f 6e ions transaction
40ba0 20 69 73 20 63 6f 6e 63 6c 75 64 65 64 2c 20 74 is concluded, t
40bb0 68 65 72 65 20 6d 61 79 20 62 65 0a 2a 2a 20 6d here may be.** m
40bc0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 62 6c 6f ore than one blo
40bd0 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 cked connection
40be0 74 68 61 74 20 68 61 73 20 72 65 67 69 73 74 65 that has registe
40bf0 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 red for an unloc
40c00 6b 2d 6e 6f 74 69 66 79 0a 2a 2a 20 63 61 6c 6c k-notify.** call
40c10 62 61 63 6b 2e 20 49 66 20 74 77 6f 20 6f 72 20 back. If two or
40c20 6d 6f 72 65 20 73 75 63 68 20 62 6c 6f 63 6b 65 more such blocke
40c30 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 68 61 d connections ha
40c40 76 65 20 73 70 65 63 69 66 69 65 64 20 74 68 65 ve specified the
40c50 0a 2a 2a 20 73 61 6d 65 20 63 61 6c 6c 62 61 63 .** same callbac
40c60 6b 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 65 6e k function, then
40c70 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f instead of invo
40c80 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 king the callbac
40c90 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 k function.** mu
40ca0 6c 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 69 74 ltiple times, it
40cb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 is invoked once
40cc0 20 77 69 74 68 20 74 68 65 20 73 65 74 20 6f 66 with the set of
40cd0 20 76 6f 69 64 2a 20 63 6f 6e 74 65 78 74 20 70 void* context p
40ce0 6f 69 6e 74 65 72 73 0a 2a 2a 20 73 70 65 63 69 ointers.** speci
40cf0 66 69 65 64 20 62 79 20 74 68 65 20 62 6c 6f 63 fied by the bloc
40d00 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ked connections
40d10 62 75 6e 64 6c 65 64 20 74 6f 67 65 74 68 65 72 bundled together
40d20 20 69 6e 74 6f 20 61 6e 20 61 72 72 61 79 2e 0a into an array..
40d30 2a 2a 20 54 68 69 73 20 67 69 76 65 73 20 74 68 ** This gives th
40d40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 61 6e e application an
40d50 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 20 opportunity to
40d60 70 72 69 6f 72 69 74 69 7a 65 20 61 6e 79 20 61 prioritize any a
40d70 63 74 69 6f 6e 73 20 0a 2a 2a 20 72 65 6c 61 74 ctions .** relat
40d80 65 64 20 74 6f 20 74 68 65 20 73 65 74 20 6f 66 ed to the set of
40d90 20 75 6e 62 6c 6f 63 6b 65 64 20 64 61 74 61 62 unblocked datab
40da0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e ase connections.
40db0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 61 64 6c 6f .**.** <b>Deadlo
40dc0 63 6b 20 44 65 74 65 63 74 69 6f 6e 3c 2f 62 3e ck Detection</b>
40dd0 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67 20 .**.** Assuming
40de0 74 68 61 74 20 61 66 74 65 72 20 72 65 67 69 73 that after regis
40df0 74 65 72 69 6e 67 20 66 6f 72 20 61 6e 20 75 6e tering for an un
40e00 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
40e10 62 61 63 6b 20 61 20 0a 2a 2a 20 64 61 74 61 62 back a .** datab
40e20 61 73 65 20 77 61 69 74 73 20 66 6f 72 20 74 68 ase waits for th
40e30 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 e callback to be
40e40 20 69 73 73 75 65 64 20 62 65 66 6f 72 65 20 74 issued before t
40e50 61 6b 69 6e 67 20 61 6e 79 20 66 75 72 74 68 65 aking any furthe
40e60 72 0a 2a 2a 20 61 63 74 69 6f 6e 20 28 61 20 72 r.** action (a r
40e70 65 61 73 6f 6e 61 62 6c 65 20 61 73 73 75 6d 70 easonable assump
40e80 74 69 6f 6e 29 2c 20 74 68 65 6e 20 75 73 69 6e tion), then usin
40e90 67 20 74 68 69 73 20 41 50 49 20 6d 61 79 20 63 g this API may c
40ea0 61 75 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c ause the.** appl
40eb0 69 63 61 74 69 6f 6e 20 74 6f 20 64 65 61 64 6c ication to deadl
40ec0 6f 63 6b 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 ock. For example
40ed0 2c 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 , if connection
40ee0 58 20 69 73 20 77 61 69 74 69 6e 67 20 66 6f 72 X is waiting for
40ef0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 59 .** connection Y
40f00 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 's transaction t
40f10 6f 20 62 65 20 63 6f 6e 63 6c 75 64 65 64 2c 20 o be concluded,
40f20 61 6e 64 20 73 69 6d 69 6c 61 72 6c 79 20 63 6f and similarly co
40f30 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 59 20 69 73 nnection.** Y is
40f40 20 77 61 69 74 69 6e 67 20 6f 6e 20 63 6f 6e 6e waiting on conn
40f50 65 63 74 69 6f 6e 20 58 27 73 20 74 72 61 6e 73 ection X's trans
40f60 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 6e 65 69 action, then nei
40f70 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a ther connection.
40f80 2a 2a 20 77 69 6c 6c 20 70 72 6f 63 65 65 64 20 ** will proceed
40f90 61 6e 64 20 74 68 65 20 73 79 73 74 65 6d 20 6d and the system m
40fa0 61 79 20 72 65 6d 61 69 6e 20 64 65 61 64 6c 6f ay remain deadlo
40fb0 63 6b 65 64 20 69 6e 64 65 66 69 6e 69 74 65 6c cked indefinitel
40fc0 79 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 y..**.** To avoi
40fd0 64 20 74 68 69 73 20 73 63 65 6e 61 72 69 6f 2c d this scenario,
40fe0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 75 6e 6c the sqlite3_unl
40ff0 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 70 65 72 ock_notify() per
41000 66 6f 72 6d 73 20 64 65 61 64 6c 6f 63 6b 0a 2a forms deadlock.*
41010 2a 20 64 65 74 65 63 74 69 6f 6e 2e 20 49 66 20 * detection. If
41020 61 20 67 69 76 65 6e 20 63 61 6c 6c 20 74 6f 20 a given call to
41030 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e sqlite3_unlock_n
41040 6f 74 69 66 79 28 29 20 77 6f 75 6c 64 20 70 75 otify() would pu
41050 74 20 74 68 65 0a 2a 2a 20 73 79 73 74 65 6d 20 t the.** system
41060 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 65 64 20 in a deadlocked
41070 73 74 61 74 65 2c 20 74 68 65 6e 20 53 51 4c 49 state, then SQLI
41080 54 45 5f 4c 4f 43 4b 45 44 20 69 73 20 72 65 74 TE_LOCKED is ret
41090 75 72 6e 65 64 20 61 6e 64 20 6e 6f 0a 2a 2a 20 urned and no.**
410a0 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 unlock-notify ca
410b0 6c 6c 62 61 63 6b 20 69 73 20 72 65 67 69 73 74 llback is regist
410c0 65 72 65 64 2e 20 54 68 65 20 73 79 73 74 65 6d ered. The system
410d0 20 69 73 20 73 61 69 64 20 74 6f 20 62 65 20 69 is said to be i
410e0 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 65 n.** a deadlocke
410f0 64 20 73 74 61 74 65 20 69 66 20 63 6f 6e 6e 65 d state if conne
41100 63 74 69 6f 6e 20 41 20 68 61 73 20 72 65 67 69 ction A has regi
41110 73 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e stered for an un
41120 6c 6f 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a 20 63 lock-notify.** c
41130 61 6c 6c 62 61 63 6b 20 6f 6e 20 74 68 65 20 63 allback on the c
41140 6f 6e 63 6c 75 73 69 6f 6e 20 6f 66 20 63 6f 6e onclusion of con
41150 6e 65 63 74 69 6f 6e 20 42 27 73 20 74 72 61 6e nection B's tran
41160 73 61 63 74 69 6f 6e 2c 20 61 6e 64 20 63 6f 6e saction, and con
41170 6e 65 63 74 69 6f 6e 0a 2a 2a 20 42 20 68 61 73 nection.** B has
41180 20 69 74 73 65 6c 66 20 72 65 67 69 73 74 65 72 itself register
41190 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b ed for an unlock
411a0 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b -notify callback
411b0 20 77 68 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e when connection
411c0 0a 2a 2a 20 41 27 73 20 74 72 61 6e 73 61 63 74 .** A's transact
411d0 69 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 65 64 ion is concluded
411e0 2e 20 49 6e 64 69 72 65 63 74 20 64 65 61 64 6c . Indirect deadl
411f0 6f 63 6b 20 69 73 20 61 6c 73 6f 20 64 65 74 65 ock is also dete
41200 63 74 65 64 2c 20 73 6f 0a 2a 2a 20 74 68 65 20 cted, so.** the
41210 73 79 73 74 65 6d 20 69 73 20 61 6c 73 6f 20 63 system is also c
41220 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 onsidered to be
41230 64 65 61 64 6c 6f 63 6b 65 64 20 69 66 20 63 6f deadlocked if co
41240 6e 6e 65 63 74 69 6f 6e 20 42 20 68 61 73 0a 2a nnection B has.*
41250 2a 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 * registered for
41260 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 an unlock-notif
41270 79 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 74 68 y callback on th
41280 65 20 63 6f 6e 63 6c 75 73 69 6f 6e 20 6f 66 20 e conclusion of
41290 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 27 connection.** C'
412a0 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 77 s transaction, w
412b0 68 65 72 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 here connection
412c0 43 20 69 73 20 77 61 69 74 69 6e 67 20 6f 6e 20 C is waiting on
412d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 41 2e 20 41 6e connection A. An
412e0 79 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 6c y.** number of l
412f0 65 76 65 6c 73 20 6f 66 20 69 6e 64 69 72 65 63 evels of indirec
41300 74 69 6f 6e 20 61 72 65 20 61 6c 6c 6f 77 65 64 tion are allowed
41310 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 22 ..**.** <b>The "
41320 44 52 4f 50 20 54 41 42 4c 45 22 20 45 78 63 65 DROP TABLE" Exce
41330 70 74 69 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 ption</b>.**.**
41340 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b When a call to [
41350 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
41360 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4c returns SQLITE_L
41370 4f 43 4b 45 44 2c 20 69 74 20 69 73 20 61 6c 6d OCKED, it is alm
41380 6f 73 74 20 0a 2a 2a 20 61 6c 77 61 79 73 20 61 ost .** always a
41390 70 70 72 6f 70 72 69 61 74 65 20 74 6f 20 63 61 ppropriate to ca
413a0 6c 6c 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 ll sqlite3_unloc
413b0 6b 5f 6e 6f 74 69 66 79 28 29 2e 20 54 68 65 72 k_notify(). Ther
413c0 65 20 69 73 20 68 6f 77 65 76 65 72 2c 0a 2a 2a e is however,.**
413d0 20 6f 6e 65 20 65 78 63 65 70 74 69 6f 6e 2e 20 one exception.
413e0 57 68 65 6e 20 65 78 65 63 75 74 69 6e 67 20 61 When executing a
413f0 20 22 44 52 4f 50 20 54 41 42 4c 45 22 20 6f 72 "DROP TABLE" or
41400 20 22 44 52 4f 50 20 49 4e 44 45 58 22 20 73 74 "DROP INDEX" st
41410 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 53 51 4c 69 atement,.** SQLi
41420 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 65 te checks if the
41430 72 65 20 61 72 65 20 61 6e 79 20 63 75 72 72 65 re are any curre
41440 6e 74 6c 79 20 65 78 65 63 75 74 69 6e 67 20 53 ntly executing S
41450 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 ELECT statements
41460 0a 2a 2a 20 74 68 61 74 20 62 65 6c 6f 6e 67 20 .** that belong
41470 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 6e to the same conn
41480 65 63 74 69 6f 6e 2e 20 49 66 20 74 68 65 72 65 ection. If there
41490 20 61 72 65 2c 20 53 51 4c 49 54 45 5f 4c 4f 43 are, SQLITE_LOC
414a0 4b 45 44 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e KED is.** return
414b0 65 64 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 ed. In this case
414c0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 22 62 6c there is no "bl
414d0 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f ocking connectio
414e0 6e 22 2c 20 73 6f 20 69 6e 76 6f 6b 69 6e 67 0a n", so invoking.
414f0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 ** sqlite3_unloc
41500 6b 5f 6e 6f 74 69 66 79 28 29 20 72 65 73 75 6c k_notify() resul
41510 74 73 20 69 6e 20 74 68 65 20 75 6e 6c 6f 63 6b ts in the unlock
41520 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b -notify callback
41530 20 62 65 69 6e 67 0a 2a 2a 20 69 6e 76 6f 6b 65 being.** invoke
41540 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 49 d immediately. I
41550 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
41560 6e 20 74 68 65 6e 20 72 65 2d 61 74 74 65 6d 70 n then re-attemp
41570 74 73 20 74 68 65 20 22 44 52 4f 50 20 54 41 42 ts the "DROP TAB
41580 4c 45 22 0a 2a 2a 20 6f 72 20 22 44 52 4f 50 20 LE".** or "DROP
41590 49 4e 44 45 58 22 20 71 75 65 72 79 2c 20 61 6e INDEX" query, an
415a0 20 69 6e 66 69 6e 69 74 65 20 6c 6f 6f 70 20 6d infinite loop m
415b0 69 67 68 74 20 62 65 20 74 68 65 20 72 65 73 75 ight be the resu
415c0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 77 61 lt..**.** One wa
415d0 79 20 61 72 6f 75 6e 64 20 74 68 69 73 20 70 72 y around this pr
415e0 6f 62 6c 65 6d 20 69 73 20 74 6f 20 63 68 65 63 oblem is to chec
415f0 6b 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 65 k the extended e
41600 72 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 6e rror code return
41610 65 64 0a 2a 2a 20 62 79 20 61 6e 20 73 71 6c 69 ed.** by an sqli
41620 74 65 33 5f 73 74 65 70 28 29 20 63 61 6c 6c 2e te3_step() call.
41630 20 49 66 20 74 68 65 72 65 20 69 73 20 61 20 62 If there is a b
41640 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 locking connecti
41650 6f 6e 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 on, then the.**
41660 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
41670 6f 64 65 20 69 73 20 73 65 74 20 74 6f 20 53 51 ode is set to SQ
41680 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 LITE_LOCKED_SHAR
41690 45 44 43 41 43 48 45 2e 20 4f 74 68 65 72 77 69 EDCACHE. Otherwi
416a0 73 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 73 70 se, in.** the sp
416b0 65 63 69 61 6c 20 22 44 52 4f 50 20 54 41 42 4c ecial "DROP TABL
416c0 45 2f 49 4e 44 45 58 22 20 63 61 73 65 2c 20 74 E/INDEX" case, t
416d0 68 65 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f he extended erro
416e0 72 20 63 6f 64 65 20 69 73 20 6a 75 73 74 20 0a r code is just .
416f0 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 ** SQLITE_LOCKED
41700 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
41710 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f int sqlite3_unlo
41720 63 6b 5f 6e 6f 74 69 66 79 28 0a 20 20 73 71 6c ck_notify(. sql
41730 69 74 65 33 20 2a 70 42 6c 6f 63 6b 65 64 2c 20 ite3 *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 20 2f 2a 20 57 61 69 74 /* Wait
41760 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a ing connection *
41770 2f 0a 20 20 76 6f 69 64 20 28 2a 78 4e 6f 74 69 /. void (*xNoti
41780 66 79 29 28 76 6f 69 64 20 2a 2a 61 70 41 72 67 fy)(void **apArg
41790 2c 20 69 6e 74 20 6e 41 72 67 29 2c 20 20 20 20 , int nArg),
417a0 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 /* Callback func
417b0 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 2a tion to invoke *
417c0 2f 0a 20 20 76 6f 69 64 20 2a 70 4e 6f 74 69 66 /. void *pNotif
417d0 79 41 72 67 20 20 20 20 20 20 20 20 20 20 20 20 yArg
417e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
417f0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 70 /* Argument to p
41800 61 73 73 20 74 6f 20 78 4e 6f 74 69 66 79 20 2a ass to xNotify *
41810 2f 0a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 /.);.../*.** CAP
41820 49 33 52 45 46 3a 20 53 74 72 69 6e 67 20 43 6f I3REF: String Co
41830 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 45 58 50 45 mparison.** EXPE
41840 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
41850 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e he [sqlite3_strn
41860 69 63 6d 70 28 29 5d 20 41 50 49 20 61 6c 6c 6f icmp()] API allo
41870 77 73 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ws applications
41880 61 6e 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 and extensions t
41890 6f 0a 2a 2a 20 63 6f 6d 70 61 72 65 20 74 68 65 o.** compare the
418a0 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 77 6f contents of two
418b0 20 62 75 66 66 65 72 73 20 63 6f 6e 74 61 69 6e buffers contain
418c0 69 6e 67 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ing UTF-8 string
418d0 73 20 69 6e 20 61 0a 2a 2a 20 63 61 73 65 2d 69 s in a.** case-i
418e0 6e 64 65 6e 64 65 6e 74 20 66 61 73 68 69 6f 6e ndendent fashion
418f0 2c 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 , using the same
41900 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 63 definition of c
41910 61 73 65 20 69 6e 64 65 70 65 6e 64 65 6e 63 65 ase independence
41920 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 .** that SQLite
41930 20 75 73 65 73 20 69 6e 74 65 72 6e 61 6c 6c 79 uses internally
41940 20 77 68 65 6e 20 63 6f 6d 70 61 72 69 6e 67 20 when comparing
41950 69 64 65 6e 74 69 66 69 65 72 73 2e 0a 2a 2f 0a identifiers..*/.
41960 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
41970 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 qlite3_strnicmp(
41980 63 6f 6e 73 74 20 63 68 61 72 20 2a 2c 20 63 6f const char *, co
41990 6e 73 74 20 63 68 61 72 20 2a 2c 20 69 6e 74 29 nst char *, int)
419a0 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 ;../*.** Undo th
419b0 65 20 68 61 63 6b 20 74 68 61 74 20 63 6f 6e 76 e hack that conv
419c0 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f erts floating po
419d0 69 6e 74 20 74 79 70 65 73 20 74 6f 20 69 6e 74 int types to int
419e0 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75 69 6c eger for.** buil
419f0 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f 72 73 ds on processors
41a00 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 74 69 6e without floatin
41a10 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2e g point support.
41a20 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
41a30 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f E_OMIT_FLOATING_
41a40 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20 64 6f POINT.# undef do
41a50 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 69 66 uble.#endif..#if
41a60 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a def __cplusplus.
41a70 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74 68 65 } /* End of the
41a80 20 27 65 78 74 65 72 6e 20 22 43 22 27 20 62 6c 'extern "C"' bl
41a90 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 ock */.#endif.#e
41aa0 6e 64 69 66 0a 0a ndif..