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 2f 2a 0a 2a 2a 20 54 68 65 73 ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 o mark those.**
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 ther deprecated
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 use deprecated
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 y. Application
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 e aware that.**
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a ed. But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 t and gone back
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 RIMENTAL../*.**
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 _NUMBER.# undef
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 SQLITE_VERSION]
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 te3.h header.**
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65 " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 umber (always 3
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 for.** SQLite3)
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 macro resolves
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 with the value
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 SION_NUMBER for
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 t is derived. E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 ither Y will.**
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 remented.** and
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 Z will be reset
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 </a>. ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 nt system. ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d RSION "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 VERS--".#define
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 D "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 rsion.**.** Thes
10b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f e interfaces pro
10c0: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e vide the same in
10d0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 formation as the
10e0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
10f0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 ],.** [SQLITE_VE
1100: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 RSION_NUMBER], a
1110: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 nd [SQLITE_SOURC
1120: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 E_ID] C preproce
1130: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 ssor macros.** b
1140: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 ut are associate
1150: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 d with the libra
1160: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 ry instead of th
1170: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 e header file.
1180: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 ^(Cautious.** pr
1190: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 ogrammers might
11a0: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 include assert()
11b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 statements in t
11c0: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e heir application
11d0: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 to.** verify th
11e0: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e at values return
11f0: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 ed by these inte
1200: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 rfaces match the
1210: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 macros in.** th
1220: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 e header, and th
1230: 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 us insure that t
1240: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
1250: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 s.** compiled wi
1260: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 th matching libr
1270: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 ary and header f
1280: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f iles..**.** <blo
1290: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
12a0: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 assert( sqlite3
12b0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
12c0: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 er()==SQLITE_VER
12d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a SION_NUMBER );.*
12e0: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 * assert( strcmp
12f0: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 (sqlite3_sourcei
1300: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 d(),SQLITE_SOURC
1310: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 E_ID)==0 );.** a
1320: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 ssert( strcmp(sq
1330: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1340: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f (),SQLITE_VERSIO
1350: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 N)==0 );.** </pr
1360: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 e></blockquote>)
1370: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
1380: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 ite3_version[] s
1390: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 tring constant c
13a0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 ontains the text
13b0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 of [SQLITE_VERS
13c0: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 ION].** macro.
13d0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 ^The sqlite3_lib
13e0: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 version() functi
13f0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 on returns a poi
1400: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 nter to the.** t
1410: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 o the sqlite3_ve
1420: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 rsion[] string c
1430: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 onstant. The sq
1440: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1450: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 ().** function i
1460: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 s provided for u
1470: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 se in DLLs since
1480: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c DLL users usual
1490: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a ly do not have.*
14a0: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 * direct access
14b0: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 to string consta
14c0: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 nts within the D
14d0: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c LL. ^The.** sql
14e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
14f0: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f number() functio
1500: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 n returns an int
1510: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a eger equal to.**
1520: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
1530: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 _NUMBER]. ^The
1540: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 sqlite3_sourceid
1550: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 20 70 6f () function a po
1560: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74 inter.** to a st
1570: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 ring constant wh
1580: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 ose value is the
1590: 20 73 61 6d 65 20 61 73 20 74 68 65 20 5b 53 51 same as the [SQ
15a0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 0a LITE_SOURCE_ID].
15b0: 2a 2a 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f ** C preprocesso
15c0: 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 r macro..**.** S
15d0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
15e0: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 _version()] and
15f0: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 [sqlite_source_i
1600: 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f d()]..*/.SQLITE_
1610: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 EXTERN const cha
1620: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f r sqlite3_versio
1630: 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 n[];.const char
1640: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 *sqlite3_libvers
1650: 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 ion(void);.const
1660: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 char *sqlite3_s
1670: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 ourceid(void);.i
1680: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 nt sqlite3_libve
1690: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 rsion_number(voi
16a0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
16b0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 REF: Test To See
16c0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 If The Library
16d0: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a Is Threadsafe.**
16e0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
16f0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 _threadsafe() fu
1700: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a nction returns z
1710: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 ero if and only
1720: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 if.** SQLite was
1730: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69 compiled mutexi
1740: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
1750: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
1760: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1770: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1780: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
1790: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
17a0: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
17b0: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
17c0: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
17d0: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
17e0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
17f0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
1800: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
1810: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
1820: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
1830: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
1840: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
1850: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
1860: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
1870: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
1880: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
1890: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
18a0: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
18b0: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
18c0: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
18d0: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
18e0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
18f0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
1900: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
1910: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
1920: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
1930: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
1940: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
1950: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
1960: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
1970: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
1980: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
1990: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
19a0: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
19b0: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
19c0: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
19d0: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
19e0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
19f0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
1a00: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
1a10: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
1a20: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
1a30: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
1a40: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
1a50: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
1a60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
1a70: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
1a80: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
1a90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1aa0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
1ab0: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
1ac0: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
1ad0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
1ae0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
1af0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1b00: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
1b10: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
1b20: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
1b30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
1b40: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
1b50: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
1b60: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
1b70: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
1b80: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
1b90: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
1ba0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
1bb0: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
1bc0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
1bd0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
1be0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
1bf0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
1c00: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
1c10: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
1c20: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e ]. ^(The return
1c30: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
1c40: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
1c50: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 afe() function s
1c60: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f hows only the co
1c70: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 mpile-time setti
1c80: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 ng of.** thread
1c90: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 safety, not any
1ca0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 run-time changes
1cb0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 to that setting
1cc0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 made by.** sqli
1cd0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e te3_config(). In
1ce0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
1cf0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
1d00: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 rom sqlite3_thre
1d10: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 adsafe().** is u
1d20: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c nchanged by call
1d30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e s to sqlite3_con
1d40: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 fig().)^.**.** S
1d50: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
1d60: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
1d70: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
1d80: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
1d90: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1da0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 _threadsafe(void
1db0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1dc0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
1dd0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a nection Handle.*
1de0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 * KEYWORDS: {dat
1df0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1e00: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e } {database conn
1e10: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 ections}.**.** E
1e20: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 ach open SQLite
1e30: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 database is repr
1e40: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 esented by a poi
1e50: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
1e60: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 nce of.** the op
1e70: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e aque structure n
1e80: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 amed "sqlite3".
1e90: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f It is useful to
1ea0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c think of an sql
1eb0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ite3.** pointer
1ec0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 as an object. T
1ed0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
1ee0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
1ef0: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 en16()], and.**
1f00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
1f10: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 ()] interfaces a
1f20: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 re its construct
1f30: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ors, and [sqlite
1f40: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 3_close()].** is
1f50: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e its destructor.
1f60: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 There are many
1f70: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 other interface
1f80: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 s (such as.** [s
1f90: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1fa0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 2()], [sqlite3_c
1fb0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
1fc0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
1fd0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
1fe0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 )] to name but t
1ff0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d hree) that are m
2000: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 ethods on an.**
2010: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a sqlite3 object..
2020: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
2030: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 t sqlite3 sqlite
2040: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3;../*.** CAPI3R
2050: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 EF: 64-Bit Integ
2060: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 er Types.** KEYW
2070: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 ORDS: sqlite_int
2080: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 64 sqlite_uint64
2090: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
20a0: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 here is no cross
20b0: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f -platform way to
20c0: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 specify 64-bit
20d0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a integer types.**
20e0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 SQLite includes
20f0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 typedefs for 64
2100: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 -bit signed and
2110: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 unsigned integer
2120: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
2130: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 ite3_int64 and s
2140: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 qlite3_uint64 ar
2150: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 e the preferred
2160: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 type definitions
2170: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f ..** The sqlite_
2180: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2190: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 _uint64 types ar
21a0: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 e supported for
21b0: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d backwards.** com
21c0: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e patibility only.
21d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
21e0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 te3_int64 and sq
21f0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 lite_int64 types
2200: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 can store integ
2210: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 er values.** bet
2220: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 ween -9223372036
2230: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 854775808 and +9
2240: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 2233720368547758
2250: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 07 inclusive. ^
2260: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 The.** sqlite3_u
2270: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2280: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 _uint64 types ca
2290: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 n store integer
22a0: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 values .** betwe
22b0: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 en 0 and +184467
22c0: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 44073709551615 i
22d0: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 nclusive..*/.#if
22e0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
22f0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 _TYPE. typedef
2300: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
2310: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a E sqlite_int64;.
2320: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
2330: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ed SQLITE_INT64_
2340: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 TYPE sqlite_uint
2350: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64;.#elif define
2360: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 d(_MSC_VER) || d
2370: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 efined(__BORLAND
2380: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f C__). typedef _
2390: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e _int64 sqlite_in
23a0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
23b0: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 nsigned __int64
23c0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
23d0: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c else. typedef l
23e0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
23f0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
2400: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f edef unsigned lo
2410: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 ng long int sqli
2420: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 te_uint64;.#endi
2430: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 f.typedef sqlite
2440: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 _int64 sqlite3_i
2450: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 nt64;.typedef sq
2460: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 lite_uint64 sqli
2470: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a te3_uint64;../*.
2480: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 ** If compiling
2490: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 for a processor
24a0: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 that lacks float
24b0: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 ing point suppor
24c0: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 t,.** substitute
24d0: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f integer for flo
24e0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a ating-point..*/.
24f0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d #ifdef SQLITE_OM
2500: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e IT_FLOATING_POIN
2510: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c T.# define doubl
2520: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a e sqlite3_int64.
2530: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
2540: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 PI3REF: Closing
2550: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 A Database Conne
2560: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ction.**.** ^The
2570: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2580: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 routine is the
2590: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 destructor for t
25a0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
25b0: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ect..** ^Calls t
25c0: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 o sqlite3_close(
25d0: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f ) return SQLITE_
25e0: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 OK if the [sqlit
25f0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a e3] object is.**
2600: 20 73 75 63 63 65 73 73 66 75 6c 6c 6c 79 20 64 successfullly d
2610: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c estroyed and all
2620: 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f associated reso
2630: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f urces are deallo
2640: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 cated..**.** App
2650: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b lications must [
2660: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2670: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c | finalize] all
2680: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2690: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ments].** and [s
26a0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
26b0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b e | close] all [
26c0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 BLOB handles] as
26d0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a sociated with.**
26e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
26f0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 bject prior to a
2700: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f ttempting to clo
2710: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 se the object.
2720: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 ^If.** sqlite3_c
2730: 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 lose() is called
2740: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 on a [database
2750: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
2760: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 still has.** ou
2770: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 tstanding [prepa
2780: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 red statements]
2790: 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 or [BLOB handles
27a0: 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 ], then it retur
27b0: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 ns.** SQLITE_BUS
27c0: 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 Y..**.** ^If [sq
27d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 lite3_close()] i
27e0: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 s invoked while
27f0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
2800: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 open,.** the tr
2810: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 ansaction is aut
2820: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
2830: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
2840: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f e C parameter to
2850: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
2860: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 C)] must be eith
2870: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 er a NULL.** poi
2880: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 nter or an [sqli
2890: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e te3] object poin
28a0: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ter obtained.**
28b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 from [sqlite3_op
28c0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
28d0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a open16()], or.**
28e0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
28f0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 2()], and not pr
2900: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e eviously closed.
2910: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c .** ^Calling sql
2920: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 ite3_close() wit
2930: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
2940: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a argument is a .
2950: 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f ** harmless no-o
2960: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 p..*/.int sqlite
2970: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 3_close(sqlite3
2980: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 *);../*.** The t
2990: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 ype for a callba
29a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 ck function..**
29b0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 This is legacy a
29c0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 nd deprecated.
29d0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 It is included f
29e0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a or historical.**
29f0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 compatibility a
2a00: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 nd is not docume
2a10: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 nted..*/.typedef
2a20: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 int (*sqlite3_c
2a30: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 allback)(void*,i
2a40: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a nt,char**, char*
2a50: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2a60: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 REF: One-Step Qu
2a70: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e ery Execution In
2a80: 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 terface.**.** Th
2a90: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
2aa0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 interface is a
2ab0: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 convenience wrap
2ac0: 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 per around.** [s
2ad0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2ae0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 2()], [sqlite3_s
2af0: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c tep()], and [sql
2b00: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
2b10: 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 ,.** that allows
2b20: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
2b30: 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 to run multiple
2b40: 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 statements of SQ
2b50: 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 L.** without hav
2b60: 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 ing to use a lot
2b70: 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a of C code. .**.
2b80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2b90: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 exec() interface
2ba0: 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f runs zero or mo
2bb0: 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 re UTF-8 encoded
2bc0: 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 ,.** semicolon-s
2bd0: 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 eparate SQL stat
2be0: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e ements passed in
2bf0: 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d to its 2nd argum
2c00: 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 ent,.** in the c
2c10: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 ontext of the [d
2c20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2c30: 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 on] passed in as
2c40: 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 its 1st.** argu
2c50: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 ment. ^If the c
2c60: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
2c70: 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 of the 3rd argu
2c80: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 ment to.** sqlit
2c90: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 e3_exec() is not
2ca0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 NULL, then it i
2cb0: 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 s invoked for ea
2cc0: 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a ch result row.**
2cd0: 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 coming out of t
2ce0: 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c he evaluated SQL
2cf0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 statements. ^T
2d00: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 he 4th argument
2d10: 74 6f 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 to.** to sqlite3
2d20: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 _exec() is relay
2d30: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 ed through to th
2d40: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f e 1st argument o
2d50: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 f each.** callba
2d60: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 ck invocation.
2d70: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
2d80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 pointer to sqli
2d90: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
2da0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 NULL, then no c
2db0: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 allback is ever
2dc0: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 invoked and resu
2dd0: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 lt rows are.** i
2de0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 gnored..**.** ^I
2df0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
2e00: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 s while evaluati
2e10: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ng the SQL state
2e20: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 ments passed int
2e30: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
2e40: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 c(), then execut
2e50: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 ion of the curre
2e60: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f nt statement sto
2e70: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 ps and.** subseq
2e80: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 uent statements
2e90: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 are skipped. ^I
2ea0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
2eb0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
2ec0: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 xec().** is not
2ed0: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 NULL then any er
2ee0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 ror message is w
2ef0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f ritten into memo
2f00: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ry obtained.** f
2f10: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
2f20: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 loc()] and passe
2f30: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 d back through t
2f40: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
2f50: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 ..** To avoid me
2f60: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 mory leaks, the
2f70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
2f80: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 ld invoke [sqlit
2f90: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e e3_free()].** on
2fa0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
2fb0: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
2fc0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 through the 5th
2fd0: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 parameter of.**
2fe0: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 of sqlite3_exec(
2ff0: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f ) after the erro
3000: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
3010: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 is no longer ne
3020: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 eded..** ^If the
3030: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
3040: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3050: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 is not NULL and
3060: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 no errors.** oc
3070: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 cur, then sqlite
3080: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 3_exec() sets th
3090: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 e pointer in its
30a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
30b0: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 o.** NULL before
30c0: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a returning..**.*
30d0: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 * ^If an sqlite3
30e0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
30f0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
3100: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 o, the sqlite3_e
3110: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 xec().** routine
3120: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
3130: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e ABORT without in
3140: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 voking the callb
3150: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a ack again and.**
3160: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 without running
3170: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 any subsequent
3180: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
3190: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 **.** ^The 2nd a
31a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
31b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
31c0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
31d0: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
31e0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
31f0: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 he result. ^The
3200: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 3rd argument to
3210: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 the sqlite3_exe
3220: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 c().** callback
3230: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
3240: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
3250: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 gs obtained as i
3260: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 f from.** [sqlit
3270: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
3280: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 ], one for each
3290: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 column. ^If an
32a0: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 element of a.**
32b0: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 result row is NU
32c0: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 LL then the corr
32d0: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 esponding string
32e0: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 pointer for the
32f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3300: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 () callback is a
3310: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
3320: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e ^The 4th argumen
3330: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 t to the.** sqli
3340: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3350: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 ack is an array
3360: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 of pointers to s
3370: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 trings where eac
3380: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 h.** entry repre
3390: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f sents the name o
33a0: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 f corresponding
33b0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 result column as
33c0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
33d0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d m [sqlite3_colum
33e0: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_name()]..**.**
33f0: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 ^If the 2nd par
3400: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3410: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 3_exec() is a NU
3420: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f LL pointer, a po
3430: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 inter.** to an e
3440: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 mpty string, or
3450: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 a pointer that c
3460: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 ontains only whi
3470: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a tespace and/or .
3480: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c ** SQL comments,
3490: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 then no SQL sta
34a0: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c tements are eval
34b0: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 uated and the da
34c0: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 tabase.** is not
34d0: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 changed..**.**
34e0: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a Restrictions:.**
34f0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
3500: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
3510: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 must insure tha
3520: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 t the 1st parame
3530: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3540: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 xec().** is
3550: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 a valid and ope
3560: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
3570: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e ection]..** <li>
3580: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
3590: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 must not close
35a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
35b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
35c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 by.** the 1
35d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
35e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 sqlite3_exec() w
35f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 hile sqlite3_exe
3600: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a c() is running..
3610: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c ** <li> The appl
3620: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
3630: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 modify the SQL
3640: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 statement text p
3650: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 assed into.**
3660: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d the 2nd param
3670: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
3680: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c exec() while sql
3690: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 ite3_exec() is r
36a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e unning..** </ul>
36b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
36c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
36d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
36e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
36f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
3700: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
3710: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
3720: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3730: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
3740: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
3750: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
3760: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
3770: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
3780: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
3790: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
37a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
37b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
37c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
37d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
37e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
37f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
3800: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3810: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
3820: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
3830: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3840: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
3850: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
3860: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d _OK {error code}
3870: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a {error codes}.*
3880: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 * KEYWORDS: {res
3890: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c ult code} {resul
38a0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d t codes}.**.** M
38b0: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 any SQLite funct
38c0: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 ions return an i
38d0: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f nteger result co
38e0: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 de from the set
38f0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e shown.** here in
3900: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 order to indica
3910: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 tes success or f
3920: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 ailure..**.** Ne
3930: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 w error codes ma
3940: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
3950: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
3960: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 SQLite..**.** S
3970: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
3980: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 _IOERR_READ | ex
3990: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
39a0: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 des].*/.#define
39b0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 SQLITE_OK
39c0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 0 /* Succe
39d0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a ssful result */.
39e0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d /* beginning-of-
39f0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 error-codes */.#
3a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 define SQLITE_ER
3a10: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f ROR 1 /
3a20: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d * SQL error or m
3a30: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 issing database
3a40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3a50: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 E_INTERNAL 2
3a60: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c /* Internal l
3a70: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 ogic error in SQ
3a80: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 Lite */.#define
3a90: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 SQLITE_PERM
3aa0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 3 /* Acces
3ab0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e s permission den
3ac0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
3ad0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 QLITE_ABORT
3ae0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 4 /* Callba
3af0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 ck routine reque
3b00: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f sted an abort */
3b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3b20: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 BUSY 5
3b30: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
3b40: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 file is locked
3b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3b60: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 E_LOCKED 6
3b70: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e /* A table in
3b80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
3b90: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
3ba0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 ne SQLITE_NOMEM
3bb0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 7 /* A
3bc0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 malloc() failed
3bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3be0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 E_READONLY 8
3bf0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f /* Attempt to
3c00: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c write a readonl
3c10: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 y database */.#d
3c20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
3c30: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a ERRUPT 9 /*
3c40: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 Operation termi
3c50: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 nated by sqlite3
3c60: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 _interrupt()*/.#
3c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
3c80: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f ERR 10 /
3c90: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 * Some kind of d
3ca0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 isk I/O error oc
3cb0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e curred */.#defin
3cc0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 e SQLITE_CORRUPT
3cd0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 11 /* The
3ce0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 database disk i
3cf0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 mage is malforme
3d00: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
3d10: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 ITE_NOTFOUND
3d20: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 12 /* NOT USED
3d30: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 . Table or recor
3d40: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 d not found */.#
3d50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
3d60: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f LL 13 /
3d70: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c * Insertion fail
3d80: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 ed because datab
3d90: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 ase is full */.#
3da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
3db0: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f NTOPEN 14 /
3dc0: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e * Unable to open
3dd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
3de0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 le */.#define SQ
3df0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 LITE_PROTOCOL
3e00: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 15 /* NOT USE
3e10: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b D. Database lock
3e20: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 protocol error
3e30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3e40: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 E_EMPTY 16
3e50: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 /* Database i
3e60: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 s empty */.#defi
3e70: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 ne SQLITE_SCHEMA
3e80: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 17 /* Th
3e90: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
3ea0: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 a changed */.#de
3eb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 fine SQLITE_TOOB
3ec0: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 IG 18 /*
3ed0: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 String or BLOB e
3ee0: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 xceeds size limi
3ef0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
3f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 ITE_CONSTRAINT
3f10: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 19 /* Abort du
3f20: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 e to constraint
3f30: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 violation */.#de
3f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d fine SQLITE_MISM
3f50: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 ATCH 20 /*
3f60: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 Data type mismat
3f70: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ch */.#define SQ
3f80: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 LITE_MISUSE
3f90: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 21 /* Library
3fa0: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c used incorrectl
3fb0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
3fc0: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 ITE_NOLFS
3fd0: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 22 /* Uses OS
3fe0: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 features not sup
3ff0: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a ported on host *
4000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4010: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 _AUTH 23
4020: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 /* Authorizati
4030: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 on denied */.#de
4040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d fine SQLITE_FORM
4050: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 AT 24 /*
4060: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 Auxiliary databa
4070: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 se format error
4080: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4090: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 E_RANGE 25
40a0: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 /* 2nd parame
40b0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
40c0: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 ind out of range
40d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
40e0: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 TE_NOTADB 2
40f0: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 6 /* File open
4100: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 ed that is not a
4110: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a database file *
4120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4130: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 _ROW 100
4140: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 /* sqlite3_ste
4150: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 p() has another
4160: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 row ready */.#de
4170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 fine SQLITE_DONE
4180: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 101 /*
4190: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
41a0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 as finished exec
41b0: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d uting */./* end-
41c0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a of-error-codes *
41d0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
41e0: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 F: Extended Resu
41f0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 lt Codes.** KEYW
4200: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 ORDS: {extended
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 error code} {ext
4220: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
4230: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 s}.** KEYWORDS:
4240: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 {extended result
4250: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 code} {extended
4260: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a result codes}.*
4270: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 *.** In its defa
4280: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
4290: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f n, SQLite API ro
42a0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e utines return on
42b0: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a e of 26 integer.
42c0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 ** [SQLITE_OK |
42d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 result codes].
42e0: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 However, experie
42f0: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 nce has shown th
4300: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 at many of.** th
4310: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ese result codes
4320: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d are too coarse-
4330: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 grained. They d
4340: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 o not provide as
4350: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 .** much informa
4360: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c tion about probl
4370: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 ems as programme
4380: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 rs might like.
4390: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a In an effort to.
43a0: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c ** address this,
43b0: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 newer versions
43c0: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 of SQLite (versi
43d0: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 on 3.3.8 and lat
43e0: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 er) include.** s
43f0: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 upport for addit
4400: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 ional result cod
4410: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 es that provide
4420: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e more detailed in
4430: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f formation.** abo
4440: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 ut errors. The e
4450: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
4460: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 odes are enabled
4470: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
4480: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 on a per databas
4490: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 e connection bas
44a0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 is using the.**
44b0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
44c0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
44d0: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d ] API..**.** Som
44e0: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 e of the availab
44f0: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 le extended resu
4500: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 lt codes are lis
4510: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 ted here..** One
4520: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 may expect the
4530: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 number of extend
4540: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
4550: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a will be expand.*
4560: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f * over time. So
4570: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 ftware that uses
4580: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
4590: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 codes should ex
45a0: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e pect.** to see n
45b0: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ew result codes
45c0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
45d0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
45e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f .** The SQLITE_O
45f0: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 K result code wi
4600: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 ll never be exte
4610: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 nded. It will a
4620: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 lways.** be exac
4630: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 tly zero..*/.#de
4640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4650: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 R_READ
4660: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4670: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 R | (1<<8)).#def
4680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4690: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 _SHORT_READ
46a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
46b0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
46c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
46d0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 WRITE
46e0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
46f0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (3<<8)).#defin
4700: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 e SQLITE_IOERR_F
4710: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 SYNC
4720: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4730: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (4<<8)).#define
4740: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
4750: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 R_FSYNC
4760: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4770: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (5<<8)).#define
4780: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 SQLITE_IOERR_TRU
4790: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 NCATE (
47a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
47b0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
47c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 QLITE_IOERR_FSTA
47d0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 T (S
47e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 QLITE_IOERR | (7
47f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
4800: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 LITE_IOERR_UNLOC
4810: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 K (SQ
4820: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c LITE_IOERR | (8<
4830: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4840: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b ITE_IOERR_RDLOCK
4850: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4860: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c ITE_IOERR | (9<<
4870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4880: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 TE_IOERR_DELETE
4890: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
48a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c TE_IOERR | (10<<
48b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
48c0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
48d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
48e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c TE_IOERR | (11<<
48f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4900: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 TE_IOERR_NOMEM
4910: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4920: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c TE_IOERR | (12<<
4930: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4940: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 TE_IOERR_ACCESS
4950: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4960: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c TE_IOERR | (13<<
4970: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4980: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 TE_IOERR_CHECKRE
4990: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 SERVEDLOCK (SQLI
49a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c TE_IOERR | (14<<
49b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
49c0: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 TE_IOERR_LOCK
49d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
49e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c TE_IOERR | (15<<
49f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4a00: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 TE_IOERR_CLOSE
4a10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4a20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c TE_IOERR | (16<<
4a30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4a40: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f TE_IOERR_DIR_CLO
4a50: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 SE (SQLI
4a60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c TE_IOERR | (17<<
4a70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4a80: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 TE_LOCKED_SHARED
4a90: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 CACHE (SQLI
4aa0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c TE_LOCKED | (1<<
4ab0: 38 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8) )../*.** CAPI
4ac0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 3REF: Flags For
4ad0: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 File Open Operat
4ae0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
4af0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 bit values are
4b00: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
4b10: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 in the.** 3rd p
4b20: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
4b30: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
4b40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e ()] interface an
4b50: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 d.** in the 4th
4b60: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
4b70: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 xOpen method of
4b80: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
4b90: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f _vfs] object..*/
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4bb0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
4bc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
4bd0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4be0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4c00: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
4c10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
4c20: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4c30: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4c50: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
4c60: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
4c70: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4c80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ca0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
4cb0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
4cc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ce0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
4cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
4d00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4d20: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
4d30: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
4d40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4d60: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
4d70: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
4d80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4da0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
4db0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
4dc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4de0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
4df0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
4e00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4e10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4e20: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
4e30: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
4e40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4e50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4e60: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
4e70: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
4e80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ea0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
4eb0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
4ec0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ee0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
4ef0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
4f00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4f10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4f30: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
4f40: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
4f50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4f60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4f70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4f80: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
4f90: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
4fa0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4fb0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4fc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4fd0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
4fe0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
4ff0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5000: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5010: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
5020: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 : Device Charact
5030: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 eristics.**.** T
5040: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69 he xDeviceCapabi
5050: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 lities method of
5060: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
5070: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a _methods].** obj
5080: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 ect returns an i
5090: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
50a0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 a vector of the
50b0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c these.** bit val
50c0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 ues expressing I
50d0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 /O characteristi
50e0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 cs of the mass s
50f0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 torage.** device
5100: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 that holds the
5110: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 file that the [s
5120: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5130: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e s].** refers to.
5140: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
5150: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
5160: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
5170: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
5180: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
5190: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
51a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
51b0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
51c0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
51d0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
51e0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
51f0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
5200: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
5210: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
5220: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
5230: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
5240: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
5250: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
5260: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
5270: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
5280: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
5290: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
52a0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
52b0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
52c0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
52d0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
52e0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
52f0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
5300: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5310: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
5320: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
5330: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
5340: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
5350: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
5360: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
5370: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f to xWrite()..*/
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5390: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 IOCAP_ATOMIC
53a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
53b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
53c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 IOCAP_ATOMIC512
53d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
53e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
53f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 IOCAP_ATOMIC1K
5400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
5410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5420: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 IOCAP_ATOMIC2K
5430: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0x00000008
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5450: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 IOCAP_ATOMIC4K
5460: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
5470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5480: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 IOCAP_ATOMIC8K
5490: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
54a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
54b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 IOCAP_ATOMIC16K
54c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
54e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 IOCAP_ATOMIC32K
54f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5510: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 IOCAP_ATOMIC64K
5520: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5540: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
5550: 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 D 0x00000200
5560: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5570: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
5580: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0x00000400
5590: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
55a0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c : File Locking L
55b0: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 evels.**.** SQLi
55c0: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 te uses one of t
55d0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c hese integer val
55e0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e ues as the secon
55f0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
5600: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 calls it makes
5610: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 to the xLock() a
5620: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 nd xUnlock() met
5630: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 hods.** of an [s
5640: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5650: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 s] object..*/.#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
5670: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 K_NONE
5680: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
5690: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 _LOCK_SHARED
56a0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
56b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 LITE_LOCK_RESERV
56c0: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e ED 2.#defin
56d0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 e SQLITE_LOCK_PE
56e0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 NDING 3.#d
56f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
5700: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 K_EXCLUSIVE
5710: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 4../*.** CAPI3RE
5720: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 F: Synchronizati
5730: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a on Type Flags.**
5740: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 .** When SQLite
5750: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e invokes the xSyn
5760: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e c() method of an
5770: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f .** [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
5790: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e it uses a combin
57a0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 ation of.** thes
57b0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
57c0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 as the second a
57d0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 rgument..**.** W
57e0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 hen the SQLITE_S
57f0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 YNC_DATAONLY fla
5800: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 g is used, it me
5810: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ans that the.**
5820: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f sync operation o
5830: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 nly needs to flu
5840: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 sh data to mass
5850: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a storage. Inode.
5860: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e ** information n
5870: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 eed not be flush
5880: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 ed. If the lower
5890: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 four bits of th
58a0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 e flag.** equal
58b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
58c0: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 AL, that means t
58d0: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 o use normal fsy
58e0: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a nc() semantics..
58f0: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 ** If the lower
5900: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 four bits equal
5910: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
5920: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 , that means.**
5930: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 to use Mac OS X
5940: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 style fullsync i
5950: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 nstead of fsync(
5960: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 )..*/.#define SQ
5970: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
5980: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
5990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
59a0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
59b0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
59c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
59d0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
59e0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 010../*.** CAPI3
59f0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
5a00: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 e Open File Hand
5a10: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c le.**.** An [sql
5a20: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
5a30: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 t represents an
5a40: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 open file in the
5a50: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 .** [sqlite3_vf
5a60: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 s | OS interface
5a70: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 layer]. Indivi
5a80: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
5a90: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
5aa0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
5ab0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
5ac0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
5ad0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
5ae0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
5af0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
5b00: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
5b10: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
5b20: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
5b30: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
5b40: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
5b50: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
5b60: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
5b70: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
5b80: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
5b90: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
5ba0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
5bb0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
5bc0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
5bd0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
5be0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5bf0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
5c00: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
5c10: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
5c20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
5c30: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
5c40: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
5c50: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ds Object.**.**
5c60: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 Every file opene
5c70: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
5c80: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 3_vfs] xOpen met
5c90: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e hod populates an
5ca0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
5cb0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d e] object (or, m
5cc0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 ore commonly, a
5cd0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
5ce0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
5cf0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 ] object) with a
5d00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
5d10: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
5d20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 object..** This
5d30: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
5d40: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 he methods used
5d50: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
5d60: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a us operations.**
5d70: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
5d80: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 n file represent
5d90: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
5da0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e e3_file] object.
5db0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f .**.** If the xO
5dc0: 70 65 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20 pen method sets
5dd0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
5de0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e .pMethods elemen
5df0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e t .** to a non-N
5e00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
5e10: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f n the sqlite3_io
5e20: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 _methods.xClose
5e30: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 method.** may be
5e40: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 invoked even if
5e50: 20 74 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 the xOpen repor
5e60: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c ted that it fail
5e70: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 ed. The.** only
5e80: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 way to prevent
5e90: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 a call to xClose
5ea0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 following a fai
5eb0: 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 led xOpen.** is
5ec0: 66 6f 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f for the xOpen to
5ed0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 set the sqlite3
5ee0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
5ef0: 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a lement to NULL..
5f00: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 **.** The flags
5f10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e argument to xSyn
5f20: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 c may be one of
5f30: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 [SQLITE_SYNC_NOR
5f40: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 MAL] or.** [SQLI
5f50: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 TE_SYNC_FULL].
5f60: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 The first choice
5f70: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 is the normal f
5f80: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 sync()..** The s
5f90: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 econd choice is
5fa0: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 a Mac OS X style
5fb0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 fullsync. The
5fc0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 [SQLITE_SYNC_DAT
5fd0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d AONLY].** flag m
5fe0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f ay be ORed in to
5ff0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f indicate that o
6000: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 nly the data of
6010: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 the file.** and
6020: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 not its inode ne
6030: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 eds to be synced
6040: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 ..**.** The inte
6050: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c ger values to xL
6060: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
6070: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a k() are one of.*
6080: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
6090: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
60a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
60b0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c TE_LOCK_SHARED],
60c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
60d0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c _LOCK_RESERVED],
60e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
60f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
6100: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 or.** <li> [SQLI
6110: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
6120: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 E]..** </ul>.**
6130: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 xLock() increase
6140: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c s the lock. xUnl
6150: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 ock() decreases
6160: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 the lock..** The
6170: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c xCheckReservedL
6180: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 ock() method che
6190: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 cks whether any
61a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
61b0: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 ion,.** either i
61c0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f n this process o
61d0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 r in some other
61e0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 process, is hold
61f0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a ing a RESERVED,.
6200: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 ** PENDING, or E
6210: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e XCLUSIVE lock on
6220: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 the file. It r
6230: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 eturns true.** i
6240: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 f such a lock ex
6250: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f ists and false o
6260: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 therwise..**.**
6270: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c The xFileControl
6280: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 () method is a g
6290: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 eneric interface
62a0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 that allows cus
62b0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 tom.** VFS imple
62c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 mentations to di
62d0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 rectly control a
62e0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e n open file usin
62f0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
6300: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
6310: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 ] interface. Th
6320: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 e second "op" ar
6330: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 gument is an.**
6340: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 integer opcode.
6350: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
6360: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 ent is a generic
6370: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 pointer intende
6380: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f d to.** point to
6390: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 a structure tha
63a0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 t may contain ar
63b0: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 guments or space
63c0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 in which to.**
63d0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c write return val
63e0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 ues. Potential
63f0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f uses for xFileCo
6400: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 ntrol() might be
6410: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f .** functions to
6420: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 enable blocking
6430: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 locks with time
6440: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 outs, to change
6450: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 the.** locking s
6460: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 trategy (for exa
6470: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d mple to use dot-
6480: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 file locks), to
6490: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 inquire.** about
64a0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 the status of a
64b0: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 lock, or to bre
64c0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 ak stale locks.
64d0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 The SQLite.** c
64e0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c ore reserves all
64f0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 opcodes less th
6500: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f an 100 for its o
6510: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 wn use..** A [SQ
6520: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
6530: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f TATE | list of o
6540: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 pcodes] less tha
6550: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 n 100 is availab
6560: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 le..** Applicati
6570: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 ons that define
6580: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f a custom xFileCo
6590: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f ntrol method sho
65a0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a uld use opcodes.
65b0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 ** greater than
65c0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 100 to avoid con
65d0: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 flicts..**.** Th
65e0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 e xSectorSize()
65f0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 method returns t
6600: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f he sector size o
6610: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 f the.** device
6620: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 that underlies t
6630: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 he file. The se
6640: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 ctor size is the
6650: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 .** minimum writ
6660: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 e that can be pe
6670: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 rformed without
6680: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 disturbing.** ot
6690: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 her bytes in the
66a0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 file. The xDev
66b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
66c0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 cs().** method r
66d0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 eturns a bit vec
66e0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 tor describing b
66f0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a ehaviors of the.
6700: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 ** underlying de
6710: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e vice:.**.** <ul>
6720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
6730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a _IOCAP_ATOMIC].*
6740: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
6750: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a OCAP_ATOMIC512].
6760: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6770: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a IOCAP_ATOMIC1K].
6780: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6790: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a IOCAP_ATOMIC2K].
67a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
67b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a IOCAP_ATOMIC4K].
67c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
67d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a IOCAP_ATOMIC8K].
67e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
67f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d IOCAP_ATOMIC16K]
6800: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
6810: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
6820: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
6830: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
6840: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
6850: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
6860: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 PEND].** <li> [S
6870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
6880: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e ENTIAL].** </ul>
6890: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
68a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
68b0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
68c0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
68d0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
68e0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
68f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6900: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
6910: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
6920: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
6930: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
6940: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
6950: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
6960: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
6970: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
6980: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
6990: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
69a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
69b0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
69c0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
69d0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
69e0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
69f0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
6a00: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
6a10: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
6a20: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
6a30: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
6a40: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
6a50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6a60: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
6a70: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6a80: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
6a90: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
6aa0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
6ab0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
6ac0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a to xWrite()..**
6ad0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 .** If xRead() r
6ae0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f eturns SQLITE_IO
6af0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 ERR_SHORT_READ i
6b00: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c t must also fill
6b10: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 .** in the unrea
6b20: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 d portions of th
6b30: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 e buffer with ze
6b40: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 ros. A VFS that
6b50: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 .** fails to zer
6b60: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
6b70: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f ds might seem to
6b80: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c work. However,
6b90: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a .** failure to z
6ba0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
6bb0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 eads will eventu
6bc0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 ally lead to.**
6bd0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 database corrupt
6be0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
6bf0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
6c00: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 o_methods sqlite
6c10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 3_io_methods;.st
6c20: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
6c30: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 methods {. int
6c40: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
6c50: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
6c60: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
6c70: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 (*xRead)(sqlite3
6c80: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 _file*, void*, i
6c90: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
6ca0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
6cb0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 int (*xWrite)(s
6cc0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f qlite3_file*, co
6cd0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 nst void*, int i
6ce0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
6cf0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
6d00: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 (*xTruncate)(sq
6d10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
6d20: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 ite3_int64 size)
6d30: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
6d40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
6d50: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e int flags);. in
6d60: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 t (*xFileSize)(s
6d70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
6d80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 lite3_int64 *pSi
6d90: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f ze);. int (*xLo
6da0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
6db0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
6dc0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 *xUnlock)(sqlite
6dd0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
6de0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 int (*xCheckRes
6df0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 ervedLock)(sqlit
6e00: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 e3_file*, int *p
6e10: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
6e20: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 *xFileControl)(s
6e30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
6e40: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 t op, void *pArg
6e50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 );. int (*xSect
6e60: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f orSize)(sqlite3_
6e70: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
6e80: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
6e90: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f istics)(sqlite3_
6ea0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 file*);. /* Add
6eb0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 itional methods
6ec0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
6ed0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
6ee0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
6ef0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 I3REF: Standard
6f00: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 File Control Opc
6f10: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 odes.**.** These
6f20: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
6f30: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 ts are opcodes f
6f40: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 or the xFileCont
6f50: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 rol method.** of
6f60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
6f70: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
6f80: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 and for the [sq
6f90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
6fa0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 ol()].** interfa
6fb0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 ce..**.** The [S
6fc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b QLITE_FCNTL_LOCK
6fd0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 STATE] opcode is
6fe0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 used for debugg
6ff0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 ing. This.** op
7000: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 code causes the
7010: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
7020: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 hod to write the
7030: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f current state o
7040: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f f.** the lock (o
7050: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f ne of [SQLITE_LO
7060: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 CK_NONE], [SQLIT
7070: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a E_LOCK_SHARED],.
7080: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ** [SQLITE_LOCK_
7090: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 RESERVED], [SQLI
70a0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
70b0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 , or [SQLITE_LOC
70c0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a K_EXCLUSIVE]).**
70d0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 into an integer
70e0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 that the pArg a
70f0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 rgument points t
7100: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 o. This capabili
7110: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 ty.** is used du
7120: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 ring testing and
7130: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 only needs to b
7140: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e e supported when
7150: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 SQLITE_TEST.**
7160: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 is defined..*/.#
7170: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
7180: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 NTL_LOCKSTATE
7190: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
71a0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 QLITE_GET_LOCKPR
71b0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 OXYFILE 2.#
71c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
71d0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
71e0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
71f0: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f QLITE_LAST_ERRNO
7200: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a 4..
7210: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
7220: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a Mutex Handle.**.
7230: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 ** The mutex mod
7240: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 ule within SQLit
7250: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 e defines [sqlit
7260: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 e3_mutex] to be
7270: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 an.** abstract t
7280: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 ype for a mutex
7290: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c object. The SQL
72a0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c ite core never l
72b0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 ooks.** at the i
72c0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e nternal represen
72d0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 tation of an [sq
72e0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 lite3_mutex]. I
72f0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 t only.** deals
7300: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f with pointers to
7310: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
7320: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a tex] object..**.
7330: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 ** Mutexes are c
7340: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 reated using [sq
7350: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
7360: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 c()]..*/.typedef
7370: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
7380: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 mutex sqlite3_mu
7390: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 tex;../*.** CAPI
73a0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
73b0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ce Object.**.**
73c0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
73d0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
73e0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
73f0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 e interface betw
7400: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 een.** the SQLit
7410: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 e core and the u
7420: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 nderlying operat
7430: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 ing system. The
7440: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 "vfs".** in the
7450: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a name of the obj
7460: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 ect stands for "
7470: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 virtual file sys
7480: 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tem"..**.** The
7490: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 value of the iVe
74a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 rsion field is i
74b0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d nitially 1 but m
74c0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a ay be larger in.
74d0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f ** future versio
74e0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 ns of SQLite. A
74f0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
7500: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
7510: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 to this.** obje
7520: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 ct when the iVer
7530: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e sion value is in
7540: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 creased. Note t
7550: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
7560: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
7570: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
7580: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
7590: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 ansaction betwee
75a0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 n.** SQLite vers
75b0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e ion 3.5.9 and 3.
75c0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 6.0 and yet the
75d0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 iVersion field w
75e0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 as not.** modifi
75f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
7600: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
7610: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
7620: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 subclassed [sqli
7630: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 te3_file].** str
7640: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 ucture used by t
7650: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 his VFS. mxPath
7660: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 name is the maxi
7670: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a mum length of.**
7680: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 a pathname in t
7690: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 his VFS..**.** R
76a0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 egistered sqlite
76b0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 3_vfs objects ar
76c0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b e kept on a link
76d0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 ed list formed b
76e0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 y.** the pNext p
76f0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 ointer. The [sq
7700: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
7710: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 er()].** and [sq
7720: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
7730: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 ster()] interfac
7740: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c es manage this l
7750: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 ist.** in a thre
7760: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 ad-safe way. Th
7770: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 e [sqlite3_vfs_f
7780: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ind()] interface
7790: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 .** searches the
77a0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 list. Neither
77b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
77c0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 code nor the VFS
77d0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
77e0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 on should use th
77f0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
7800: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 .**.** The pNext
7810: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e field is the on
7820: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 ly field in the
7830: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 sqlite3_vfs.** s
7840: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 tructure that SQ
7850: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d Lite will ever m
7860: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 odify. SQLite w
7870: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a ill only access.
7880: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ** or modify thi
7890: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f s field while ho
78a0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c lding a particul
78b0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e ar static mutex.
78c0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
78d0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
78e0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 modify anything
78f0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 within the sqli
7900: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 te3_vfs.** objec
7910: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 t once the objec
7920: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 t has been regis
7930: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tered..**.** The
7940: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c zName field hol
7950: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ds the name of t
7960: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 he VFS module.
7970: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a The name must.**
7980: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 be unique acros
7990: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 s all VFS module
79a0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 s..**.** SQLite
79b0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 will guarantee t
79c0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d hat the zFilenam
79d0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 e parameter to x
79e0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 Open.** is eithe
79f0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
7a00: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 or string obtai
7a10: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c ned.** from xFul
7a20: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 lPathname(). SQ
7a30: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 Lite further gua
7a40: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 rantees that.**
7a50: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 the string will
7a60: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 be valid and unc
7a70: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c hanged until xCl
7a80: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c ose() is.** call
7a90: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 ed. Because of t
7aa0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
7ab0: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 ence,.** the [sq
7ac0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 lite3_file] can
7ad0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 safely store a p
7ae0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ointer to the.**
7af0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 filename if it
7b00: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 needs to remembe
7b10: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 r the filename f
7b20: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a or some reason..
7b30: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e ** If the zFilen
7b40: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
7b50: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c xOpen is a NULL
7b60: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f pointer then xO
7b70: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 pen.** must inve
7b80: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f nt its own tempo
7b90: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 rary name for th
7ba0: 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 e file. Wheneve
7bb0: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e r the .** xFilen
7bc0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
7bd0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c NULL it will al
7be0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 so be the case t
7bf0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 hat the.** flags
7c00: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 parameter will
7c10: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f include [SQLITE_
7c20: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
7c30: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 SE]..**.** The f
7c40: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
7c50: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 xOpen() include
7c60: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 s all bits set i
7c70: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 n.** the flags a
7c80: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
7c90: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 te3_open_v2()].
7ca0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f Or if [sqlite3_
7cb0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 open()].** or [s
7cc0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
7cd0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 is used, then f
7ce0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 lags includes at
7cf0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 least.** [SQLIT
7d00: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
7d10: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ] | [SQLITE_OPEN
7d20: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 _CREATE]. .** If
7d30: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 xOpen() opens a
7d40: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 file read-only
7d50: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f then it sets *pO
7d60: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e utFlags to.** in
7d70: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 clude [SQLITE_OP
7d80: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f EN_READONLY]. O
7d90: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f ther bits in *pO
7da0: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 utFlags may be s
7db0: 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 et..**.** SQLite
7dc0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f will also add o
7dd0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
7de0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
7df0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c xOpen().** call
7e00: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
7e10: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 he object being
7e20: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 opened:.**.** <u
7e30: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c l>.** <li> [SQL
7e40: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
7e50: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
7e60: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
7e70: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
7e80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
7e90: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
7ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
7eb0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
7ec0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
7ed0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 RANSIENT_DB].**
7ee0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
7ef0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a EN_SUBJOURNAL].*
7f00: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
7f10: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
7f20: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a NAL].** </ul>.**
7f30: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f .** The file I/O
7f40: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
7f50: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 can use the obje
7f60: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f ct type flags to
7f70: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 .** change the w
7f80: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 ay it deals with
7f90: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 files. For exa
7fa0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 mple, an applica
7fb0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 tion.** that doe
7fc0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 s not care about
7fd0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 crash recovery
7fe0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 or rollback migh
7ff0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 t make.** the op
8000: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 en of a journal
8010: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 file a no-op. W
8020: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f rites to this jo
8030: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 urnal would.** a
8040: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 lso be no-ops, a
8050: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 nd any attempt t
8060: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e o read the journ
8070: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a al would return.
8080: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e ** SQLITE_IOERR.
8090: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 Or the impleme
80a0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 ntation might re
80b0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 cognize that a d
80c0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
80d0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 will be doing pa
80e0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f ge-aligned secto
80f0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 r reads and writ
8100: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a es in a random.*
8110: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 * order and set
8120: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 up its I/O subsy
8130: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 stem accordingly
8140: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d ..**.** SQLite m
8150: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e ight also add on
8160: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
8170: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
8180: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a xOpen method:.**
8190: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
81b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 LETEONCLOSE].**
81c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 <li> [SQLITE_OPE
81d0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 N_EXCLUSIVE].**
81e0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
81f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
8200: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 ETEONCLOSE] flag
8210: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 means the file
8220: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c should be.** del
8230: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 eted when it is
8240: 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51 closed. The [SQ
8250: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
8260: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c ONCLOSE].** will
8270: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 be set for TEMP
8280: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 databases, jou
8290: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 rnals and for su
82a0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a bjournals..**.**
82b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 The [SQLITE_OPE
82c0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 N_EXCLUSIVE] fla
82d0: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 g is always used
82e0: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a in conjunction.
82f0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ** with the [SQL
8300: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
8310: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 flag, which are
8320: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a both directly.*
8330: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 * analogous to t
8340: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f he O_EXCL and O_
8350: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 CREAT flags of t
8360: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a he POSIX open().
8370: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c ** API. The SQL
8380: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
8390: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 VE flag, when pa
83a0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a ired with the .*
83b0: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 * SQLITE_OPEN_CR
83c0: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f EATE, is used to
83d0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 indicate that f
83e0: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 ile should alway
83f0: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c s.** be created,
8400: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 and that it is
8410: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 an error if it a
8420: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a lready exists..*
8430: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f * It is <i>not</
8440: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 i> used to indic
8450: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f ate the file sho
8460: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a uld be opened .*
8470: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 * for exclusive
8480: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74 access..**.** At
8490: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 least szOsFile
84a0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 bytes of memory
84b0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 are allocated by
84c0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f SQLite.** to ho
84d0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 ld the [sqlite3
84e0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 _file] structure
84f0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 passed as the t
8500: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 hird.** argument
8510: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 to xOpen. The
8520: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 xOpen method doe
8530: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a s not have to.**
8540: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 allocate the st
8550: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 ructure; it shou
8560: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 ld just fill it
8570: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a in. Note that.*
8580: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 * the xOpen meth
8590: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 od must set the
85a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
85b0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a thods to either.
85c0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 ** a valid [sqli
85d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
85e0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c object or to NUL
85f0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 L. xOpen must d
8600: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 o.** this even i
8610: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 f the open fails
8620: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 . SQLite expect
8630: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 s that the sqlit
8640: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
8650: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c .** element will
8660: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 be valid after
8670: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 xOpen returns re
8680: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 gardless of the
8690: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 success.** or fa
86a0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 ilure of the xOp
86b0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 en call..**.** T
86c0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
86d0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d t to xAccess() m
86e0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 ay be [SQLITE_AC
86f0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 CESS_EXISTS].**
8700: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 to test for the
8710: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 existence of a f
8720: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ile, or [SQLITE_
8730: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
8740: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 ] to.** test whe
8750: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 ther a file is r
8760: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
8770: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 able, or [SQLITE
8780: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a _ACCESS_READ].**
8790: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 to test whether
87a0: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 a file is at le
87b0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 ast readable.
87c0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 The file can be
87d0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a a.** directory..
87e0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
87f0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 l always allocat
8800: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 e at least mxPat
8810: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f hname+1 bytes fo
8820: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 r the.** output
8830: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 buffer xFullPath
8840: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 name. The exact
8850: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 size of the out
8860: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
8870: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 also passed as
8880: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 a parameter to b
8890: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 oth methods. If
88a0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
88b0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 er.** is not lar
88c0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 ge enough, [SQLI
88d0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f TE_CANTOPEN] sho
88e0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e uld be returned.
88f0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a Since this is.*
8900: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 * handled as a f
8910: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 atal error by SQ
8920: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d Lite, vfs implem
8930: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 entations should
8940: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 endeavor.** to
8950: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 prevent this by
8960: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 setting mxPathna
8970: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 me to a sufficie
8980: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 ntly large value
8990: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e ..**.** The xRan
89a0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 domness(), xSlee
89b0: 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e p(), and xCurren
89c0: 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 tTime() interfac
89d0: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 es.** are not st
89e0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 rictly a part of
89f0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c the filesystem,
8a00: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a but they are.**
8a10: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 included in the
8a20: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 VFS structure f
8a30: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e or completeness.
8a40: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e .** The xRandomn
8a50: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 ess() function a
8a60: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 ttempts to retur
8a70: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a n nBytes bytes.*
8a80: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 * of good-qualit
8a90: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 y randomness int
8aa0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 o zOut. The ret
8ab0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 urn value is.**
8ac0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 the actual numbe
8ad0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 r of bytes of ra
8ae0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 ndomness obtaine
8af0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 d..** The xSleep
8b00: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 () method causes
8b10: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 the calling thr
8b20: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 ead to sleep for
8b30: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 at.** least the
8b40: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f number of micro
8b50: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 seconds given.
8b60: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
8b70: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
8b80: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 urns a Julian Da
8b90: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 y Number for the
8ba0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e current date an
8bb0: 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 d time..**.*/.ty
8bc0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
8bd0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 ite3_vfs sqlite3
8be0: 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c _vfs;.struct sql
8bf0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 ite3_vfs {. int
8c00: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 iVersion;
8c10: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 /* Structu
8c20: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 re version numbe
8c30: 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 r */. int szOsF
8c40: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 ile;
8c50: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c /* Size of subcl
8c60: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 assed sqlite3_fi
8c70: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 le */. int mxPa
8c80: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 thname;
8c90: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 /* Maximum file
8ca0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 pathname length
8cb0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 */. sqlite3_vf
8cc0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f s *pNext; /
8cd0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 * Next registere
8ce0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 d VFS */. const
8cf0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 char *zName;
8d00: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
8d10: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 his virtual file
8d20: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 system */. voi
8d30: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
8d40: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 /* Pointer
8d50: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d to application-
8d60: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f specific data */
8d70: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 . int (*xOpen)(
8d80: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
8d90: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
8da0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a sqlite3_file*,.
8db0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
8dc0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 nt flags, int *p
8dd0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 OutFlags);. int
8de0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 (*xDelete)(sqli
8df0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
8e00: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
8e10: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 syncDir);. int
8e20: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 (*xAccess)(sqli
8e30: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
8e40: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
8e50: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 flags, int *pRe
8e60: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
8e70: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 FullPathname)(sq
8e80: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
8e90: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
8ea0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a nt nOut, char *z
8eb0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a Out);. void *(*
8ec0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 xDlOpen)(sqlite3
8ed0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
8ee0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 r *zFilename);.
8ef0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 void (*xDlError
8f00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8f10: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 int nByte, char
8f20: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 *zErrMsg);. voi
8f30: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 d (*(*xDlSym)(sq
8f40: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a lite3_vfs*,void*
8f50: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 , const char *zS
8f60: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 ymbol))(void);.
8f70: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 void (*xDlClose
8f80: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8f90: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a void*);. int (*
8fa0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c xRandomness)(sql
8fb0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
8fc0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 Byte, char *zOut
8fd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 );. int (*xSlee
8fe0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c p)(sqlite3_vfs*,
8ff0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 int microsecond
9000: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 s);. int (*xCur
9010: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 rentTime)(sqlite
9020: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3_vfs*, double*)
9030: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 ;. int (*xGetLa
9040: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 stError)(sqlite3
9050: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 _vfs*, int, char
9060: 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 *);. /* New fi
9070: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 elds may be appe
9080: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 nded in figure v
9090: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 ersions. The iV
90a0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 ersion. ** valu
90b0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 e will increment
90c0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 whenever this h
90d0: 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f appens. */.};../
90e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
90f0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 lags for the xAc
9100: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a cess VFS method.
9110: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
9120: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 ger constants ca
9130: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 n be used as the
9140: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
9150: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 to.** the xAcce
9160: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 ss method of an
9170: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
9180: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 ject. They dete
9190: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 rmine.** what ki
91a0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e nd of permission
91b0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 s the xAccess me
91c0: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 thod is looking
91d0: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c for..** With SQL
91e0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 ITE_ACCESS_EXIST
91f0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d S, the xAccess m
9200: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 ethod.** simply
9210: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
9220: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a he file exists..
9230: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
9240: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c CCESS_READWRITE,
9250: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
9260: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 hod.** checks wh
9270: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 ether the file i
9280: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 s both readable
9290: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a and writable..**
92a0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
92b0: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 ESS_READ, the xA
92c0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
92d0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
92e0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 he file is reada
92f0: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ble..*/.#define
9300: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
9310: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e ISTS 0.#defin
9320: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
9330: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 READWRITE 1.#def
9340: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ine SQLITE_ACCES
9350: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f S_READ 2../
9360: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
9370: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 nitialize The SQ
9380: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a Lite Library.**.
9390: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
93a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
93b0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 tine initializes
93c0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c the.** SQLite l
93d0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 ibrary. ^The sq
93e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
93f0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c routine.** deal
9400: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f locates any reso
9410: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 urces that were
9420: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c allocated by sql
9430: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
9440: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 )..** These rout
9450: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 ines are designe
9460: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 d to aid in proc
9470: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ess initializati
9480: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f on and.** shutdo
9490: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 wn on embedded s
94a0: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 ystems. Worksta
94b0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e tion application
94c0: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 s using.** SQLit
94d0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f e normally do no
94e0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 t need to invoke
94f0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 either of these
9500: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
9510: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 A call to sqlit
9520: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9530: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
9540: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a " call if it is.
9550: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d ** the first tim
9560: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
9570: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
9580: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 d during the lif
9590: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 etime of.** the
95a0: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 process, or if i
95b0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 t is the first t
95c0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 ime sqlite3_init
95d0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f ialize() is invo
95e0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 ked.** following
95f0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
9600: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
9610: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 ^(Only an effect
9620: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 ive call.** of s
9630: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9640: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 e() does any ini
9650: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c tialization. Al
9660: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a l other calls.**
9670: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f are harmless no
9680: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 -ops.)^.**.** A
9690: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
96a0: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e shutdown() is an
96b0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
96c0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 l if it is the f
96d0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 irst.** call to
96e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
96f0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 () since the las
9700: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
9710: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a lize(). ^(Only.
9720: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 ** an effective
9730: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
9740: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 shutdown() does
9750: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 any deinitializa
9760: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 tion..** All oth
9770: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 er valid calls t
9780: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
9790: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 wn() are harmles
97a0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a s no-ops.)^.**.*
97b0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
97c0: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 itialize() inter
97d0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 face is threadsa
97e0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f fe, but sqlite3_
97f0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 shutdown().** is
9800: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 not. The sqlit
9810: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e e3_shutdown() in
9820: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c terface must onl
9830: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d y be called from
9840: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 a.** single thr
9850: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b ead. All open [
9860: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
9870: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c ions] must be cl
9880: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 osed and all.**
9890: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 other SQLite res
98a0: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 ources must be d
98b0: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 eallocated prior
98c0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 to invoking.**
98d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
98e0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 ()..**.** Among
98f0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 other things, ^s
9900: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9910: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a e() will invoke.
9920: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
9930: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 it(). Similarly
9940: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 , ^sqlite3_shutd
9950: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e own().** will in
9960: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f voke sqlite3_os_
9970: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 end()..**.** ^Th
9980: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
9990: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 lize() routine r
99a0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
99b0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a K] on success..*
99c0: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 * ^If for some r
99d0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 eason, sqlite3_i
99e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 nitialize() is u
99f0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c nable to initial
9a00: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 ize.** the libra
9a10: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 ry (perhaps it i
9a20: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
9a30: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 cate a needed re
9a40: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 source such.** a
9a50: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 s a mutex) it re
9a60: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 turns an [error
9a70: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e code] other than
9a80: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
9a90: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
9aa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
9ab0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
9ac0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 internally by ma
9ad0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ny other.** SQLi
9ae0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f te interfaces so
9af0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 that an applica
9b00: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 tion usually doe
9b10: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a s not need to.**
9b20: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
9b30: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
9b40: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d ectly. For exam
9b50: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ple, [sqlite3_op
9b60: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 en()].** calls s
9b70: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9b80: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 e() so the SQLit
9b90: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 e library will b
9ba0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
9bb0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 ** initialized w
9bc0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 hen [sqlite3_ope
9bd0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 n()] is called i
9be0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 f it has not be
9bf0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 initialized.** a
9c00: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 lready. ^Howeve
9c10: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 r, if SQLite is
9c20: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
9c30: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 e [SQLITE_OMIT_A
9c40: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 UTOINIT].** comp
9c50: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c ile-time option,
9c60: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 then the automa
9c70: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c tic calls to sql
9c80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
9c90: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 ).** are omitted
9ca0: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
9cb0: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 tion must call s
9cc0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9cd0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 e() directly.**
9ce0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
9cf0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
9d00: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 interface. For
9d10: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c maximum portabil
9d20: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 ity,.** it is re
9d30: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
9d40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 pplications alwa
9d50: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ys invoke sqlite
9d60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 3_initialize().*
9d70: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 * directly prior
9d80: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 to using any ot
9d90: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
9da0: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 face. Future re
9db0: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c leases.** of SQL
9dc0: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 ite may require
9dd0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 this. In other
9de0: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 words, the behav
9df0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a ior exhibited.**
9e00: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
9e10: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
9e20: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 QLITE_OMIT_AUTOI
9e30: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d NIT] might becom
9e40: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 e the.** default
9e50: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d behavior in som
9e60: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 e future release
9e70: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
9e80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 * The sqlite3_os
9e90: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 _init() routine
9ea0: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 does operating-s
9eb0: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a ystem specific.*
9ec0: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e * initialization
9ed0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c of the SQLite l
9ee0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c ibrary. The sql
9ef0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
9f00: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 routine undoes
9f10: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 the effect of sq
9f20: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e lite3_os_init().
9f30: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a Typical tasks.
9f40: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 ** performed by
9f50: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 these routines i
9f60: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f nclude allocatio
9f70: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f n or deallocatio
9f80: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 n.** of static r
9f90: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 esources, initia
9fa0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 lization of glob
9fb0: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a al variables,.**
9fc0: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 setting up a de
9fd0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
9fe0: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 fs] module, or s
9ff0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 etting up.** a d
a000: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 efault configura
a010: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 tion using [sqli
a020: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a te3_config()]..*
a030: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
a040: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
a050: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 r invoke either
a060: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
a070: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
a080: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c os_end() directl
a090: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 y. The applicat
a0a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 ion should only
a0b0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
a0c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 3_initialize() a
a0d0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 nd sqlite3_shutd
a0e0: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 own(). The sqli
a0f0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a te3_os_init().**
a100: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 interface is ca
a110: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c lled automatical
a120: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ly by sqlite3_in
a130: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a itialize() and.*
a140: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 * sqlite3_os_end
a150: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 () is called by
a160: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
a170: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 (). Appropriate
a180: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
a190: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f ons for sqlite3_
a1a0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
a1b0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
a1c0: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f * are built into
a1d0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 SQLite when it
a1e0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 is compiled for
a1f0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f Unix, Windows, o
a200: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 r OS/2..** When
a210: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c [custom builds |
a220: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 built for other
a230: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 platforms].** (
a240: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
a250: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f E_OS_OTHER=1] co
a260: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 mpile-time.** op
a270: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 tion) the applic
a280: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c ation must suppl
a290: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 y a suitable imp
a2a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a lementation for.
a2b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
a2c0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
a2d0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 _os_end(). An a
a2e0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
a2f0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ied.** implement
a300: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
a310: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 _os_init() or sq
a320: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
a330: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 * must return [S
a340: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
a350: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 cess and some ot
a360: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d her [error code]
a370: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 upon.** failure
a380: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
a390: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 _initialize(void
a3a0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 );.int sqlite3_s
a3b0: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 hutdown(void);.i
a3c0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e nt sqlite3_os_in
a3d0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 it(void);.int sq
a3e0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 lite3_os_end(voi
a3f0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
a400: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 REF: Configuring
a410: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
a420: 61 72 79 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e ary.** EXPERIMEN
a430: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 TAL.**.** The sq
a440: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
a450: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
a460: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 to make global
a470: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
a480: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 changes to SQLi
a490: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 te in order to t
a4a0: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 une SQLite to th
a4b0: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
a4c0: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
a4d0: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 cation. The def
a4e0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
a4f0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 on is recommende
a500: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 d for most.** ap
a510: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 plications and s
a520: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 o this routine i
a530: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 s usually not ne
a540: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a cessary. It is.
a550: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 ** provided to s
a560: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c upport rare appl
a570: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e ications with un
a580: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a usual needs..**.
a590: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
a5a0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
a5b0: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 e is not threads
a5c0: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 afe. The applic
a5d0: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e ation.** must in
a5e0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 sure that no oth
a5f0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
a600: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 aces are invoked
a610: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 by other.** thr
a620: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 eads while sqlit
a630: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 e3_config() is r
a640: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 unning. Further
a650: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f more, sqlite3_co
a660: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e nfig().** may on
a670: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 ly be invoked pr
a680: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 ior to library i
a690: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 nitialization us
a6a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
a6b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 initialize()] or
a6c0: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 after shutdown
a6d0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 by [sqlite3_shut
a6e0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 down()]..** ^If
a6f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
a700: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 is called after
a710: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
a720: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f lize()] and befo
a730: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 re.** [sqlite3_s
a740: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 hutdown()] then
a750: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 it will return S
a760: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a QLITE_MISUSE..**
a770: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 Note, however,
a780: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f that ^sqlite3_co
a790: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 nfig() can be ca
a7a0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
a7b0: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
a7c0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c ation of an appl
a7d0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
a7e0: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 [sqlite3_os_init
a7f0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ()]..**.** The f
a800: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
a810: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
a820: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a ) is an integer.
a830: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
a840: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c G_SINGLETHREAD |
a850: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
a860: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 ption] that dete
a870: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 rmines.** what p
a880: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 roperty of SQLit
a890: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 e is to be confi
a8a0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 gured. Subseque
a8b0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 nt arguments.**
a8c0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
a8d0: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f n the [SQLITE_CO
a8e0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
a8f0: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f D | configuratio
a900: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 n option].** in
a910: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
a920: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 nt..**.** ^When
a930: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
a940: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
a950: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
a960: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
a970: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 OK]..** ^If the
a980: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 option is unknow
a990: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 n or SQLite is u
a9a0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 nable to set the
a9b0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 option.** then
a9c0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 this routine ret
a9d0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 urns a non-zero
a9e0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f [error code]..*/
a9f0: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
aa00: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
aa10: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e _config(int, ...
aa20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
aa30: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 EF: Configure da
aa40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
aa50: 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ns.** EXPERIMENT
aa60: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c AL.**.** The sql
aa70: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
aa80: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
aa90: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
aaa0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
aab0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
aac0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
aad0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
aae0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
aaf0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
ab00: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
ab10: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
ab20: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
ab30: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
ab40: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
ab50: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
ab60: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a gument). The.**
ab70: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
ab80: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ig() interface s
ab90: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73 hould only be us
aba0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 ed immediately a
abb0: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 fter.** the data
abc0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
abd0: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 is created using
abe0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
abf0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f ],.** [sqlite3_o
ac00: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 pen16()], or [sq
ac10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
ac20: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 . .**.** The se
ac30: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
ac40: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
ac50: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 ig(D,V,...) is
ac60: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 the.** configura
ac70: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 tion verb - an i
ac80: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 nteger code that
ac90: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a indicates what.
aca0: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 ** aspect of the
acb0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
acc0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
acd0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 configured..** T
ace0: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 he only choice f
acf0: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 or this value is
ad00: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 [SQLITE_DBCONFI
ad10: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a G_LOOKASIDE]..**
ad20: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c New verbs are l
ad30: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 ikely to be adde
ad40: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
ad50: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
ad60: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 ** Additional ar
ad70: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f guments depend o
ad80: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a n the verb..**.*
ad90: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
ada0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
adb0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
adc0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a if and only if.
add0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 ** the call is c
ade0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 onsidered succes
adf0: 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f sful..*/.SQLITE_
ae00: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
ae10: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
ae20: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ig(sqlite3*, int
ae30: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a op, ...);../*.*
ae40: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
ae50: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f ry Allocation Ro
ae60: 75 74 69 6e 65 73 0a 2a 2a 20 45 58 50 45 52 49 utines.** EXPERI
ae70: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 MENTAL.**.** An
ae80: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
ae90: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
aea0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
aeb0: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 tween SQLite.**
aec0: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 and low-level me
aed0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
aee0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
aef0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 This object is u
af00: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 sed in only one
af10: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c place in the SQL
af20: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ite interface..*
af30: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * A pointer to a
af40: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
af50: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 is object is the
af60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
af70: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
af80: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 )] when the conf
af90: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
afa0: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 is.** [SQLITE_C
afb0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 ONFIG_MALLOC] or
afc0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
afd0: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a GETMALLOC]. .**
afe0: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 By creating an
aff0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
b000: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 object.** and p
b010: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 assing it to [sq
b020: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
b030: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
b040: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 LOC]).** during
b050: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 configuration, a
b060: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 n application ca
b070: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 n specify an alt
b080: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
b090: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
b0a0: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 bsystem for SQLi
b0b0: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c te to use for al
b0c0: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 l of its.** dyna
b0d0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 mic memory needs
b0e0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
b0f0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 t SQLite comes w
b100: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 ith several [bui
b110: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
b120: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 ocators].** that
b130: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 are perfectly a
b140: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 dequate for the
b150: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a overwhelming maj
b160: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
b170: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 tions.** and tha
b180: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 t this object is
b190: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 only useful to
b1a0: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 a tiny minority
b1b0: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a of applications.
b1c0: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 ** with speciali
b1d0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 zed memory alloc
b1e0: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e ation requiremen
b1f0: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 ts. This object
b200: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 is.** also used
b210: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 during testing
b220: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 of SQLite in ord
b230: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e er to specify an
b240: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
b250: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
b260: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 that simulates
b270: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 memory out-of-me
b280: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 mory conditions
b290: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 in.** order to v
b2a0: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 erify that SQLit
b2b0: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 e recovers grace
b2c0: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a fully from such.
b2d0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a ** conditions..*
b2e0: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 *.** The xMalloc
b2f0: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f and xFree metho
b300: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b ds must work lik
b310: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 e the.** malloc(
b320: 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e ) and free() fun
b330: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 ctions from the
b340: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
b350: 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c ry..** The xReal
b360: 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 loc method must
b370: 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f work like reallo
b380: 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61 c() from the sta
b390: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a ndard C library.
b3a0: 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65 ** with the exce
b3b0: 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68 ption that if th
b3c0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
b3d0: 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 t to xRealloc is
b3e0: 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c zero,.** xReall
b3f0: 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d oc must be a no-
b400: 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 op - it must not
b410: 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c perform any all
b420: 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 ocation or.** de
b430: 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 allocation. ^SQ
b440: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 Lite guarantees
b450: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 that the second
b460: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 argument to.** x
b470: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 Realloc is alway
b480: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e s a value return
b490: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 ed by a prior ca
b4a0: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a ll to xRoundup..
b4b0: 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 ** And so in cas
b4c0: 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75 es where xRoundu
b4d0: 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 p always returns
b4e0: 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 a positive numb
b4f0: 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 er,.** xRealloc
b500: 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63 can perform exac
b510: 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64 tly as the stand
b520: 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c ard library real
b530: 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 loc() and.** sti
b540: 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 ll be in complia
b550: 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70 nce with this sp
b560: 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a ecification..**.
b570: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 ** xSize should
b580: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 return the alloc
b590: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d ated size of a m
b5a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b5b0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f .** previously o
b5c0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 btained from xMa
b5d0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 lloc or xRealloc
b5e0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 . The allocated
b5f0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 size.** is alwa
b600: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 ys at least as b
b610: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 ig as the reques
b620: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 ted size but may
b630: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a be larger..**.*
b640: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d * The xRoundup m
b650: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 ethod returns wh
b660: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 at would be the
b670: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
b680: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c f.** a memory al
b690: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 location given a
b6a0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 particular requ
b6b0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 ested size. Mos
b6c0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f t memory.** allo
b6d0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
b6e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
b6f0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 ns at least to t
b700: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 he next multiple
b710: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 .** of 8. Some
b720: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 allocators round
b730: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 up to a larger
b740: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 multiple or to a
b750: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 power of 2..**
b760: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c Every memory all
b770: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 ocation request
b780: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 coming in throug
b790: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f h [sqlite3_mallo
b7a0: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 c()].** or [sqli
b7b0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 te3_realloc()] f
b7c0: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e irst calls xRoun
b7d0: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 dup. If xRoundu
b7e0: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a p returns 0, .**
b7f0: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 that causes the
b800: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d corresponding m
b810: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b820: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 to fail..**.**
b830: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 The xInit method
b840: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
b850: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
b860: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 r. (For example
b870: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c ,.** it might al
b880: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 locate any requi
b890: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e re mutexes or in
b8a0: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 itialize interna
b8b0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 l data.** struct
b8c0: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 ures. The xShut
b8d0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 down method is i
b8e0: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 nvoked (indirect
b8f0: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ly) by.** [sqlit
b900: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 e3_shutdown()] a
b910: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f nd should deallo
b920: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 cate any resourc
b930: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 es acquired.** b
b940: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 y xInit. The pA
b950: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 ppData pointer i
b960: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e s used as the on
b970: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a ly parameter to.
b980: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 ** xInit and xSh
b990: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 utdown..**.** SQ
b9a0: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b Lite holds the [
b9b0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
b9c0: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 TIC_MASTER] mute
b9d0: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 x when it invoke
b9e0: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d s.** the xInit m
b9f0: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 ethod, so the xI
ba00: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 nit method need
ba10: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 not be threadsaf
ba20: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 e. The.** xShut
ba30: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f down method is o
ba40: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 nly called from
ba50: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
ba60: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a n()] so it does.
ba70: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 ** not need to b
ba80: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 e threadsafe eit
ba90: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 her. For all ot
baa0: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c her methods, SQL
bab0: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 ite.** holds the
bac0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 [SQLITE_MUTEX_S
bad0: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 TATIC_MEM] mutex
bae0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a as long as the.
baf0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
bb00: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e G_MEMSTATUS] con
bb10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
bb20: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 n is turned on (
bb30: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 which.** it is b
bb40: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 y default) and s
bb50: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 o the methods ar
bb60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
bb70: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 serialized..** H
bb80: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 owever, if [SQLI
bb90: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
bba0: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 TUS] is disabled
bbb0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 , then the other
bbc0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 .** methods must
bbd0: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f be threadsafe o
bbe0: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 r else make thei
bbf0: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e r own arrangemen
bc00: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c ts for.** serial
bc10: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 ization..**.** S
bc20: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
bc30: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 invoke xInit()
bc40: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 more than once w
bc50: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 ithout an interv
bc60: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f ening.** call to
bc70: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f xShutdown()..*/
bc80: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
bc90: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
bca0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f ods sqlite3_mem_
bcb0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
bcc0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
bcd0: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a ods {. void *(*
bce0: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 xMalloc)(int);
bcf0: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 /* Memory
bd00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 allocation func
bd10: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 tion */. void (
bd20: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 *xFree)(void*);
bd30: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 /* Free
bd40: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 a prior allocat
bd50: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 ion */. void *(
bd60: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a *xRealloc)(void*
bd70: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a ,int); /* Resiz
bd80: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e an allocation
bd90: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 */. int (*xSize
bda0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
bdb0: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 /* Return th
bdc0: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c e size of an all
bdd0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
bde0: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 (*xRoundup)(int
bdf0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ); /* R
be00: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 ound up request
be10: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 size to allocati
be20: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 on size */. int
be30: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 (*xInit)(void*)
be40: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 ; /* I
be50: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
be60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
be70: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 /. void (*xShut
be80: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 down)(void*);
be90: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 /* Deinitiali
bea0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
beb0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
bec0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
bed0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
bee0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 rgument to xInit
bef0: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e () and xShutdown
bf00: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 () */.};../*.**
bf10: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
bf20: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
bf30: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
bf40: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
bf50: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
bf60: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
bf70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
bf80: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
bf90: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
bfa0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
bfb0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
bfc0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
bfd0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
bfe0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
bff0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
c000: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
c010: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
c020: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
c030: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
c040: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
c050: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
c060: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
c070: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
c080: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
c090: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
c0a0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
c0b0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 at.** the call w
c0c0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c orked. The [sql
c0d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
c0e0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
c0f0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
c100: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
c110: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
c120: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
c130: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
c140: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
c150: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
c160: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
c170: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
c180: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
c190: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
c1a0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
c1b0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 ion. ^This opti
c1c0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b on sets the.** [
c1d0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
c1e0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 to Single-thread
c1f0: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
c200: 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a s, it disables.*
c210: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 * all mutexing a
c220: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 nd puts SQLite i
c230: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 nto a mode where
c240: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 it can only be
c250: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e used.** by a sin
c260: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 gle thread. ^I
c270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
c280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
c290: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
c2a0: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
c2b0: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
c2c0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
c2d0: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 hen.** it is not
c2e0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 possible to cha
c2f0: 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 nge the [threadi
c300: 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 ng mode] from it
c310: 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c s default.** val
c320: 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 ue of Single-thr
c330: 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 ead and so [sqli
c340: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
c350: 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 ll return .** [S
c360: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
c370: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 called with the
c380: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
c390: 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f NGLETHREAD.** co
c3a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
c3b0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c on.</dd>.**.** <
c3c0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
c3d0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 _MULTITHREAD</dt
c3e0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
c3f0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
c400: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
c410: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
c420: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
c430: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 ding mode] to Mu
c440: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 lti-thread. In
c450: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
c460: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 disables.** mute
c470: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 xing on [databas
c480: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
c490: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
c4a0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
c4b0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
c4c0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c on is responsibl
c4d0: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e e for serializin
c4e0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b g access to.** [
c4f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
c500: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
c510: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e red statements].
c520: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 But other mute
c530: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
c540: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 ed so that SQLit
c550: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 e will be safe t
c560: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 o use in a multi
c570: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 -threaded.** env
c580: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 ironment as long
c590: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 as no two threa
c5a0: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 ds attempt to us
c5b0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 e the same.** [d
c5c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
c5d0: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 on] at the same
c5e0: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 time. ^If SQLit
c5f0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
c600: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
c610: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
c620: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
c630: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
c640: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
c650: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 it is not possib
c660: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 le to set the Mu
c670: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 lti-thread [thre
c680: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a ading mode] and.
c690: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
c6a0: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ig()] will retur
c6b0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
c6c0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 if called with
c6d0: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f the.** SQLITE_CO
c6e0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
c6f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
c700: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
c710: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
c720: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f FIG_SERIALIZED</
c730: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
c740: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
c750: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
c760: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
c770: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
c780: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
c790: 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f Serialized. In o
c7a0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 ther words, this
c7b0: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a option enables.
c7c0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 ** all mutexes i
c7d0: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 ncluding the rec
c7e0: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 ursive.** mutexe
c7f0: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
c800: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
c810: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
c820: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
c830: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 In this mode (wh
c840: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 ich is the defau
c850: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 lt when SQLite i
c860: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
c870: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 ** [SQLITE_THREA
c880: 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 DSAFE=1]) the SQ
c890: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c Lite library wil
c8a0: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 l itself seriali
c8b0: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 ze access.** to
c8c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
c8d0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
c8e0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
c8f0: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 so that the.**
c900: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 application is f
c910: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 ree to use the s
c920: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
c930: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 nnection] or the
c940: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 .** same [prepar
c950: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
c960: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
c970: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ds at the same t
c980: 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 ime..** ^If SQLi
c990: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
c9a0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
c9b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
c9c0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
c9d0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
c9e0: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
c9f0: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
ca00: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 ble to set the S
ca10: 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
ca20: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a ding mode] and.*
ca30: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
ca40: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
ca50: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
ca60: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
ca70: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e he.** SQLITE_CON
ca80: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 FIG_SERIALIZED c
ca90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
caa0: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
cab0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
cac0: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a G_MALLOC</dt>.**
cad0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 <dd> ^(This opt
cae0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
caf0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
cb00: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
cb10: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
cb20: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
cb30: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
cb40: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 ructure. The ar
cb50: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
cb60: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 .** alternative
cb70: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
cb80: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
cb90: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
cba0: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 in place of.** t
cbb0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
cbc0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 tion routines bu
cbd0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
cbe0: 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 )^ ^SQLite makes
cbf0: 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 .** its own priv
cc00: 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
cc10: 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b content of the [
cc20: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
cc30: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a ods] structure.*
cc40: 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 * before the [sq
cc50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
cc60: 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 call returns.</d
cc70: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
cc80: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
cc90: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LLOC</dt>.** <dd
cca0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
ccb0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
ccc0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
ccd0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
cce0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
ccf0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
cd00: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
cd10: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ure. The [sqlit
cd20: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a e3_mem_methods].
cd30: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 ** structure is
cd40: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 filled with the
cd50: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 currently define
cd60: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 d memory allocat
cd70: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a ion routines.)^.
cd80: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 ** This option c
cd90: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 an be used to ov
cda0: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 erload the defau
cdb0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
cdc0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 tion.** routines
cdd0: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 with a wrapper
cde0: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 that simulations
cdf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
ce00: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a on failure or.**
ce10: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 tracks memory u
ce20: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c sage, for exampl
ce30: 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c e. </dd>.**.** <
ce40: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
ce50: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a _MEMSTATUS</dt>.
ce60: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
ce70: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c tion takes singl
ce80: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 e argument of ty
ce90: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 pe int, interpre
cea0: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f ted as a .** boo
ceb0: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 lean, which enab
cec0: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
ced0: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f the collection o
cee0: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 f memory allocat
cef0: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 ion .** statisti
cf00: 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 cs. ^(When memor
cf10: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
cf20: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 tistics are disa
cf30: 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f bled, the .** fo
cf40: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 llowing SQLite i
cf50: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 nterfaces become
cf60: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c non-operational
cf70: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 :.** <ul>.**
cf80: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
cf90: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a emory_used()].**
cfa0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
cfb0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
cfc0: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b r()].** <li> [
cfd0: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
cfe0: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 p_limit()].**
cff0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 <li> [sqlite3_st
d000: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 atus()].** </u
d010: 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 l>)^.** ^Memory
d020: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
d030: 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 stics are enable
d040: 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c d by default unl
d050: 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a ess SQLite is.**
d060: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
d070: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d SQLITE_DEFAULT_M
d080: 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 EMSTATUS]=0 in w
d090: 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 hich case memory
d0a0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 .** allocation s
d0b0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 tatistics are di
d0c0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
d0d0: 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a t..** </dd>.**.*
d0e0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
d0f0: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e FIG_SCRATCH</dt>
d100: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
d110: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
d120: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
d130: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 buffer that SQLi
d140: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a te can use for.*
d150: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 * scratch memory
d160: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 . There are thr
d170: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 ee arguments: A
d180: 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 pointer an 8-by
d190: 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 te.** aligned me
d1a0: 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d mory buffer from
d1b0: 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 63 which the scrac
d1c0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 h allocations wi
d1d0: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 ll be.** drawn,
d1e0: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
d1f0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
d200: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 ion (sz),.** and
d210: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
d220: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 ber of scratch a
d230: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 llocations (N).
d240: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d The sz.** argum
d250: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 ent must be a mu
d260: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 ltiple of 16. Th
d270: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 e sz parameter s
d280: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 hould be a few b
d290: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 ytes.** larger t
d2a0: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 han the actual s
d2b0: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71 cratch space req
d2c0: 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e 74 uired due to int
d2d0: 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a ernal overhead..
d2e0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
d2f0: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 ument must be a
d300: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d pointer to an 8-
d310: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 byte aligned buf
d320: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 fer.** of at lea
d330: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 st sz*N bytes of
d340: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c memory..** ^SQL
d350: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 ite will use no
d360: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 more than one sc
d370: 72 61 74 63 68 20 62 75 66 66 65 72 20 70 65 72 ratch buffer per
d380: 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 thread. So.**
d390: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 N should be set
d3a0: 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20 to the expected
d3b0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
d3c0: 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53 51 4c f threads. ^SQL
d3d0: 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 ite will.** neve
d3e0: 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 r require a scra
d3f0: 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 tch buffer that
d400: 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 20 74 is more than 6 t
d410: 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 imes the databas
d420: 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65 2e 20 e.** page size.
d430: 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 ^If SQLite needs
d440: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 needs additiona
d450: 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 l scratch memory
d460: 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74 beyond .** what
d470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
d480: 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 this configurati
d490: 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 on option, then
d4a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
d4b0: 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 loc()] will be u
d4c0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 sed to obtain th
d4d0: 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e e memory needed.
d4e0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
d4f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
d500: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 GECACHE</dt>.**
d510: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
d520: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
d530: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
d540: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 er that SQLite c
d550: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 an use for.** th
d560: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 e database page
d570: 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 cache with the d
d580: 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 efault page cach
d590: 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e e implemenation.
d5a0: 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 .** This confi
d5b0: 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 guration should
d5c0: 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 not be used if a
d5d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
d5e0: 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 fine page.** cac
d5f0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
d600: 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e n is loaded usin
d610: 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e g the SQLITE_CON
d620: 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f FIG_PCACHE optio
d630: 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 n..** There are
d640: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 three arguments
d650: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 to this option:
d660: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 A pointer to 8-b
d670: 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d yte aligned.** m
d680: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 emory, the size
d690: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 of each page buf
d6a0: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 fer (sz), and th
d6b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
d6c0: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a s (N)..** The sz
d6d0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
d6e0: 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 be the size of
d6f0: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 the largest data
d700: 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 base page.** (a
d710: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 power of two bet
d720: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 ween 512 and 327
d730: 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 68) plus a littl
d740: 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 e extra for each
d750: 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e .** page header.
d760: 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 ^The page head
d770: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f er size is 20 to
d780: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 40 bytes depend
d790: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f ing on.** the ho
d7a0: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e st architecture.
d7b0: 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 ^It is harmles
d7c0: 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 s, apart from th
d7d0: 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c e wasted memory,
d7e0: 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 .** to make sz a
d7f0: 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 little too larg
d800: 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a e. The first.**
d810: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
d820: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c point to an all
d830: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 ocation of at le
d840: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
d850: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 f memory..** ^SQ
d860: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 Lite will use th
d870: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 e memory provide
d880: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 d by the first a
d890: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 rgument to satis
d8a0: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 fy its.** memory
d8b0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 needs for the f
d8c0: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 irst N pages tha
d8d0: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 t it adds to cac
d8e0: 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f he. ^If additio
d8f0: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 nal.** page cach
d900: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 e memory is need
d910: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 ed beyond what i
d920: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 s provided by th
d930: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a is option, then.
d940: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 ** SQLite goes t
d950: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
d960: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 c()] for the add
d970: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 itional storage
d980: 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 space..** ^The i
d990: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 mplementation mi
d9a0: 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d ght use one or m
d9b0: 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 ore of the N buf
d9c0: 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a fers to hold .**
d9d0: 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 memory accounti
d9e0: 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 ng information.
d9f0: 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 The pointer in t
da00: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
da10: 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 t must.** be ali
da20: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
da30: 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 e boundary or su
da40: 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f bsequent behavio
da50: 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 r of SQLite.** w
da60: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 ill be undefined
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 48 >SQLITE_CONFIG_H
da90: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAP</dt>.** <dd>
daa0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 ^This option sp
dab0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
dac0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
dad0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
dae0: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f use.** for all o
daf0: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 f its dynamic me
db00: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
db10: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f needs beyond tho
db20: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 se provided.** f
db30: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f or by [SQLITE_CO
db40: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e NFIG_SCRATCH] an
db50: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 d [SQLITE_CONFIG
db60: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 _PAGECACHE]..**
db70: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
db80: 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d arguments: An 8-
db90: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 byte aligned poi
dba0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f nter to the memo
dbb0: 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 ry,.** the numbe
dbc0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
dbd0: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c e memory buffer,
dbe0: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d and the minimum
dbf0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
dc00: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 ..** ^If the fir
dc10: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 st pointer (the
dc20: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 memory pointer)
dc30: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 is NULL, then SQ
dc40: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 Lite reverts.**
dc50: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 to using its def
dc60: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ault memory allo
dc70: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 cator (the syste
dc80: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 m malloc() imple
dc90: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 mentation),.** u
dca0: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 ndoing any prior
dcb0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b invocation of [
dcc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
dcd0: 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a LLOC]. ^If the.
dce0: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 ** memory pointe
dcf0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e r is not NULL an
dd00: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 d either [SQLITE
dd10: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d _ENABLE_MEMSYS3]
dd20: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 or.** [SQLITE_E
dd30: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 NABLE_MEMSYS5] a
dd40: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e re defined, then
dd50: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 the alternative
dd60: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
dd70: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 ator is engaged
dd80: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 to handle all of
dd90: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 SQLites memory
dda0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
ddb0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 ..** The first p
ddc0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
ddd0: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 ry pointer) must
dde0: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
ddf0: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e n 8-byte.** boun
de00: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 dary or subseque
de10: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 nt behavior of S
de20: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e QLite will be un
de30: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
de40: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
de50: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e ONFIG_MUTEX</dt>
de60: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
de70: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
de80: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
de90: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
dea0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
deb0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
dec0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
ded0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
dee0: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 he argument spec
def0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 ifies.** alterna
df00: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
df10: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f utex routines to
df20: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 be used in plac
df30: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 e.** the mutex r
df40: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
df50: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 to SQLite.)^ ^S
df60: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
df70: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e py of the.** con
df80: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c tent of the [sql
df90: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
dfa0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 ds] structure be
dfb0: 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f fore the call to
dfc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
dfd0: 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 fig()] returns.
dfe0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
dff0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
e000: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
e010: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
e020: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
e030: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
e040: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 then.** the ent
e050: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 ire mutexing sub
e060: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 system is omitte
e070: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 d from the build
e080: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 and hence calls
e090: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
e0a0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 config()] with t
e0b0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
e0c0: 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 _MUTEX configura
e0d0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c tion option will
e0e0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
e0f0: 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a TE_ERROR].</dd>.
e100: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
e110: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
e120: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
e130: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
e140: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
e150: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
e160: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
e170: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
e180: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
e190: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
e1a0: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 e. The.** [sqli
e1b0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
e1c0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
e1d0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
e1e0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
e1f0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 ined mutex routi
e200: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f nes.)^.** This o
e210: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
e220: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 d to overload th
e230: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 e default mutex
e240: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f allocation.** ro
e250: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 utines with a wr
e260: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 apper used to tr
e270: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 ack mutex usage
e280: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a for performance.
e290: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 ** profiling or
e2a0: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 testing, for exa
e2b0: 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 mple. ^If SQLi
e2c0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
e2d0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
e2e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
e2f0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
e300: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
e310: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
e320: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 the entire mute
e330: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 xing subsystem i
e340: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 s omitted from t
e350: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e he build and hen
e360: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b ce calls to.** [
e370: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
e380: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 ] with the SQLIT
e390: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
e3a0: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 X configuration
e3b0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 option will.** r
e3c0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
e3d0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ROR].</dd>.**.**
e3e0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
e3f0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 IG_LOOKASIDE</dt
e400: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
e410: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 option takes tw
e420: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 o arguments that
e430: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 determine the d
e440: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 efault.** memory
e450: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 allocation for
e460: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 the lookaside me
e470: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f mory allocator o
e480: 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 n each.** [datab
e490: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
e4a0: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 The first argu
e4b0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
e4c0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
e4d0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
e4e0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 t and the second
e4f0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
e500: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 f.** slots alloc
e510: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 ated to each dat
e520: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
e530: 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 .)^ ^(This opti
e540: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c on sets the.** <
e550: 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f i>default</i> lo
e560: 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 okaside size. Th
e570: 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 e [SQLITE_DBCONF
e580: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a IG_LOOKASIDE].**
e590: 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 verb to [sqlite
e5a0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 3_db_config()] c
e5b0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 an be used to ch
e5c0: 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 ange the lookasi
e5d0: 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 de.** configurat
e5e0: 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 ion on individua
e5f0: 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e l connections.)^
e600: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
e610: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
e620: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 CACHE</dt>.** <d
e630: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
e640: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
e650: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
e660: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a s a pointer to.*
e670: 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 * an [sqlite3_pc
e680: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 ache_methods] ob
e690: 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 ject. This obje
e6a0: 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 ct specifies the
e6b0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f interface.** to
e6c0: 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 a custom page c
e6d0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
e6e0: 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 ion.)^ ^SQLite
e6f0: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
e700: 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e the.** object an
e710: 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 d uses it for pa
e720: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 ge cache memory
e730: 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 allocations.</dd
e740: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
e750: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
e760: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
e770: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
e780: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
e790: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
e7a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
e7b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 ** [sqlite3_pcac
e7c0: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 he_methods] obje
e7d0: 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 ct. SQLite copi
e7e0: 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e es of the curren
e7f0: 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 t.** page cache
e800: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
e810: 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e nto that object.
e820: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c )^ </dd>.**.** <
e830: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
e840: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
e850: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f NGLETHREAD 1 /
e860: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
e870: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
e880: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 ULTITHREAD 2
e890: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
e8a0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
e8b0: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 SERIALIZED 3
e8c0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
e8d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
e8e0: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 _MALLOC 4
e8f0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
e900: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
e910: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
e920: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 IG_GETMALLOC
e930: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 5 /* sqlite3_m
e940: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
e950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
e960: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 NFIG_SCRATCH
e970: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 6 /* void*,
e980: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f int sz, int N */
e990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e9a0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
e9b0: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 7 /* void*
e9c0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
e9d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
e9e0: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 E_CONFIG_HEAP
e9f0: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 8 /* voi
ea00: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 d*, int nByte, i
ea10: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e nt min */.#defin
ea20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
ea30: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 MEMSTATUS 9
ea40: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 /* boolean */.#
ea50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
ea60: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 NFIG_MUTEX
ea70: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 10 /* sqlite3
ea80: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
ea90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
eaa0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
eab0: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c X 11 /* sql
eac0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
ead0: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f ds* */./* previo
eae0: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 usly SQLITE_CONF
eaf0: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 IG_CHUNKALLOC 12
eb00: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e which is now un
eb10: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e used. */ .#defin
eb20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
eb30: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 LOOKASIDE 13
eb40: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 /* int int */.#
eb50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
eb60: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 NFIG_PCACHE
eb70: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 14 /* sqlite3
eb80: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a _pcache_methods*
eb90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
eba0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
ebb0: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 CHE 15 /* sq
ebc0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
ebd0: 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 hods* */../*.**
ebe0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
ebf0: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
ec00: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
ec10: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
ec20: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
ec30: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
ec40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
ec50: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
ec60: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
ec70: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
ec80: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
ec90: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
eca0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
ecb0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
ecc0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
ecd0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
ece0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
ecf0: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
ed00: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
ed10: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
ed20: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
ed30: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
ed40: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
ed50: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
ed60: 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f m [sqlite3_db_co
ed70: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
ed80: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
ed90: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e call worked. ^
eda0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f The [sqlite3_db_
edb0: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
edc0: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
edd0: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
ede0: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
edf0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
ee00: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
ee10: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
ee20: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
ee30: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
ee40: 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
ee50: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
ee60: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
ee70: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 ption takes thre
ee80: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 e additional arg
ee90: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
eea0: 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c rmine the .** [l
eeb0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
eec0: 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 allocator] confi
eed0: 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 guration for the
eee0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
eef0: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 ction]..** ^The
ef00: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 first argument (
ef10: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
ef20: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
ef30: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 db_config()] is
ef40: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
ef50: 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 an memory buffer
ef60: 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b to use for look
ef70: 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a aside memory..**
ef80: 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
ef90: 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 ment after the S
efa0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
efb0: 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a OOKASIDE verb.**
efc0: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 may be NULL in
efd0: 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 which case SQLit
efe0: 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 e will allocate
eff0: 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 the.** lookaside
f000: 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 buffer itself u
f010: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 sing [sqlite3_ma
f020: 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 lloc()]. ^The se
f030: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
f040: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 the.** size of
f050: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 each lookaside b
f060: 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 uffer slot. ^Th
f070: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
f080: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
f090: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 f.** slots. The
f0a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
f0b0: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 fer in the first
f0c0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 argument must b
f0d0: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a e greater than.*
f0e0: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 * or equal to th
f0f0: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 e product of the
f100: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 second and thir
f110: 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 d arguments. Th
f120: 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 e buffer.** must
f130: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
f140: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 n 8-byte boundar
f150: 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f y. ^If the seco
f160: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
f170: 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 * SQLITE_DBCONFI
f180: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e G_LOOKASIDE is n
f190: 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 ot a multiple of
f1a0: 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 8, it is intern
f1b0: 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 ally.** rounded
f1c0: 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 down to the next
f1d0: 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 smaller.** mult
f1e0: 69 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20 iple of 8. See
f1f0: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f also: [SQLITE_CO
f200: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c NFIG_LOOKASIDE]<
f210: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
f220: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
f230: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
f240: 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f ASIDE 1001 /
f250: 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 * void* int int
f260: 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */.../*.** CAPI3
f270: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
f280: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 isable Extended
f290: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a Result Codes.**.
f2a0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
f2b0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f extended_result_
f2c0: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 codes() routine
f2d0: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
f2e0: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 les the.** [exte
f2f0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
f300: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 s] feature of SQ
f310: 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e Lite. ^The exten
f320: 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ded result.** co
f330: 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 des are disabled
f340: 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 by default for
f350: 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 historical compa
f360: 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 tibility..*/.int
f370: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
f380: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 d_result_codes(s
f390: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f qlite3*, int ono
f3a0: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ff);../*.** CAPI
f3b0: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 3REF: Last Inser
f3c0: 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 t Rowid.**.** ^E
f3d0: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 ach entry in an
f3e0: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 SQLite table has
f3f0: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 a unique 64-bit
f400: 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 signed.** integ
f410: 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 er key called th
f420: 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 e [ROWID | "rowi
f430: 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 d"]. ^The rowid
f440: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 is always availa
f450: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 ble.** as an und
f460: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e eclared column n
f470: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c amed ROWID, OID,
f480: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c or _ROWID_ as l
f490: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 ong as those.**
f4a0: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c names are not al
f4b0: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 so used by expli
f4c0: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 citly declared c
f4d0: 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 olumns. ^If.** t
f4e0: 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 he table has a c
f4f0: 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 olumn of type [I
f500: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
f510: 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f EY] then that co
f520: 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 lumn.** is anoth
f530: 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 er alias for the
f540: 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 rowid..**.** ^T
f550: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
f560: 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 rns the [rowid]
f570: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 of the most rece
f580: 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c nt.** successful
f590: 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 [INSERT] into t
f5a0: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d he database from
f5b0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
f5c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e onnection].** in
f5d0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
f5e0: 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20 73 75 63 ent. ^If no suc
f5f0: 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
f600: 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
f610: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 ccurred on that
f620: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
f630: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 ion, zero is ret
f640: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 urned..**.** ^(I
f650: 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 f an [INSERT] oc
f660: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 curs within a tr
f670: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 igger, then the
f680: 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 [rowid] of the i
f690: 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 nserted.** row i
f6a0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
f6b0: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f is routine as lo
f6c0: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 ng as the trigge
f6d0: 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a r is running..**
f6e0: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 But once the tr
f6f0: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 igger terminates
f700: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 , the value retu
f710: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 rned by this rou
f720: 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 tine.** reverts
f730: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 to the last valu
f740: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 e inserted befor
f750: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69 e the trigger fi
f760: 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e red.)^.**.** ^An
f770: 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 [INSERT] that f
f780: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f ails due to a co
f790: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
f7a0: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 on is not a.** s
f7b0: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
f7c0: 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 T] and does not
f7d0: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
f7e0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
f7f0: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e s.** routine. ^
f800: 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 Thus INSERT OR F
f810: 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 AIL, INSERT OR I
f820: 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 GNORE, INSERT OR
f830: 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e ROLLBACK,.** an
f840: 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 d INSERT OR ABOR
f850: 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 T make no change
f860: 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 s to the return
f870: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a value of this.**
f880: 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 routine when th
f890: 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 eir insertion fa
f8a0: 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 ils. ^(When INS
f8b0: 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a ERT OR REPLACE.*
f8c0: 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 * encounters a c
f8d0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
f8e0: 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 ion, it does not
f8f0: 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 fail. The.** I
f900: 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 NSERT continues
f910: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 to completion af
f920: 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 ter deleting row
f930: 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a s that caused.**
f940: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 the constraint
f950: 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 problem so INSER
f960: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c T OR REPLACE wil
f970: 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a l always change.
f980: 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ** the return va
f990: 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 lue of this inte
f9a0: 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e rface.)^.**.** ^
f9b0: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 For the purposes
f9c0: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
f9d0: 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 , an [INSERT] is
f9e0: 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a considered to.*
f9f0: 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 * be successful
fa00: 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 even if it is su
fa10: 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 bsequently rolle
fa20: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
fa30: 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 is function is a
fa40: 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c ccessible to SQL
fa50: 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 statements via
fa60: 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 the.** [last_ins
fa70: 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 ert_rowid() SQL
fa80: 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
fa90: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
faa0: 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 hread performs a
fab0: 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e new [INSERT] on
fac0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 the same.** dat
fad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
fae0: 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 while the [sqli
faf0: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
fb00: 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 rowid()].** func
fb10: 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 tion is running
fb20: 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 and thus changes
fb30: 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 the last insert
fb40: 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 [rowid],.** the
fb50: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
fb60: 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
fb70: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
fb80: 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 id()] is.** unpr
fb90: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 edictable and mi
fba0: 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 ght not equal ei
fbb0: 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 ther the old or
fbc0: 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 the new.** last
fbd0: 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a insert [rowid]..
fbe0: 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 */.sqlite3_int64
fbf0: 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
fc00: 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 sert_rowid(sqlit
fc10: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
fc20: 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 I3REF: Count The
fc30: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
fc40: 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e Modified.**.** ^
fc50: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
fc60: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
fc70: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 of database row
fc80: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e s that were chan
fc90: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 ged.** or insert
fca0: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 ed or deleted by
fcb0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
fcc0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c ly completed SQL
fcd0: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e statement.** on
fce0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
fcf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
fd00: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 fied by the firs
fd10: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 t parameter..**
fd20: 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 ^(Only changes t
fd30: 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 hat are directly
fd40: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
fd50: 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 e [INSERT], [UPD
fd60: 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c ATE],.** or [DEL
fd70: 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 ETE] statement a
fd80: 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 re counted. Aux
fd90: 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 iliary changes c
fda0: 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 aused by.** trig
fdb0: 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e gers or [foreign
fdc0: 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 key actions] ar
fdd0: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e e not counted.)^
fde0: 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c Use the.** [sql
fdf0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
fe00: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 es()] function t
fe10: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c o find the total
fe20: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 number of chang
fe30: 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 es.** including
fe40: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
fe50: 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 y triggers and f
fe60: 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
fe70: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 ns..**.** ^Chang
fe80: 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 es to a view tha
fe90: 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 t are simulated
fea0: 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f by an [INSTEAD O
feb0: 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 F trigger].** ar
fec0: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 e not counted.
fed0: 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 Only real table
fee0: 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e changes are coun
fef0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 ted..**.** ^(A "
ff00: 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 row change" is a
ff10: 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e change to a sin
ff20: 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e gle row of a sin
ff30: 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 gle table.** cau
ff40: 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 sed by an INSERT
ff50: 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 , DELETE, or UPD
ff60: 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 ATE statement.
ff70: 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 Rows that.** are
ff80: 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 changed as side
ff90: 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 effects of [REP
ffa0: 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 LACE] constraint
ffb0: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 resolution,.**
ffc0: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 rollback, ABORT
ffd0: 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f processing, [DRO
ffe0: 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 P TABLE], or by
fff0: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 any other.** mec
10000 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 hanisms do not c
10010 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 ount as direct r
10020 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a ow changes.)^.**
10030 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 .** A "trigger c
10040 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f ontext" is a sco
10050 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 pe of execution
10060 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a that begins and.
10070 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 ** ends with the
10080 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 script of a [CR
10090 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
100a0 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 rigger]. .** Mos
100b0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 t SQL statements
100c0 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 are.** evaluate
100d0 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 d outside of any
100e0 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 trigger. This
100f0 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 is the "top leve
10100 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f l".** trigger co
10110 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 ntext. If a tri
10120 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 gger fires from
10130 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 the top level, a
10140 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 .** new trigger
10150 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 context is enter
10160 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 ed for the durat
10170 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a ion of that one.
10180 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 ** trigger. Sub
10190 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 triggers create
101a0 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 subcontexts for
101b0 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a their duration..
101c0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b **.** ^Calling [
101d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
101e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 or [sqlite3_step
101f0 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 ()] recursively
10200 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 does.** not crea
10210 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 te a new trigger
10220 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
10230 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 ^This function r
10240 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
10250 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 r of direct row
10260 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a changes in the.*
10270 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e * most recent IN
10280 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
10290 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
102a0 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d t within the sam
102b0 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e e.** trigger con
102c0 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 text..**.** ^Thu
102d0 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 s, when called f
102e0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 rom the top leve
102f0 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e l, this function
10300 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 returns the.**
10310 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 number of change
10320 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 s in the most re
10330 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 cent INSERT, UPD
10340 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
10350 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 * that also occu
10360 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 rred at the top
10370 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e level. ^(Within
10380 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 the body of a t
10390 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 rigger,.** the s
103a0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
103b0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
103c0 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 e called to find
103d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
103e0 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 * changes in the
103f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 most recently c
10400 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c ompleted INSERT,
10410 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
10420 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 TE.** statement
10430 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 within the body
10440 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 of the same trig
10450 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ger..** However,
10460 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 the number retu
10470 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e rned does not in
10480 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a clude changes.**
10490 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 caused by subtr
104a0 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f iggers since tho
104b0 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 se have their ow
104c0 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a n context.)^.**.
104d0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 ** See also the
104e0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
104f0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 hanges()] interf
10500 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 ace, the.** [cou
10510 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d nt_changes pragm
10520 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 a], and the [cha
10530 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 nges() SQL funct
10540 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 ion]..**.** If a
10550 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
10560 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f makes changes o
10570 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 n the same datab
10580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
10590 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 * while [sqlite3
105a0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 _changes()] is r
105b0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 unning then the
105c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a value returned.*
105d0 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 * is unpredictab
105e0 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 le and not meani
105f0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ngful..*/.int sq
10600 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 lite3_changes(sq
10610 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
10620 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 CAPI3REF: Total
10630 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d Number Of Rows M
10640 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 odified.**.** ^T
10650 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
10660 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
10670 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 of row changes c
10680 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 aused by [INSERT
10690 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f ],.** [UPDATE] o
106a0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
106b0 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 ments since the
106c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
106d0 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 tion] was opened
106e0 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 ..** ^(The count
106f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
10700 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
10710 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c es() includes al
10720 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f l changes.** fro
10730 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 m all [CREATE TR
10740 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d IGGER | trigger]
10750 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 contexts and ch
10760 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a anges made by.**
10770 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 [foreign key ac
10780 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c tions]. However,
10790 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f .** the count do
107a0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 es not include c
107b0 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 hanges used to i
107c0 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 mplement [REPLAC
107d0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a E] constraints,.
107e0 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 ** do rollbacks
107f0 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 or ABORT process
10800 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 ing, or [DROP TA
10810 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e BLE] processing.
10820 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 The.** count d
10830 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
10840 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 rows of views th
10850 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 at fire an [INST
10860 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c EAD OF trigger],
10870 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 .** though if th
10880 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 e INSTEAD OF tri
10890 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 gger makes chang
108a0 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 es of its own, t
108b0 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a hose changes .**
108c0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a are counted.)^.
108d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
108e0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 total_changes()
108f0 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 function counts
10900 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 the changes as s
10910 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 oon as.** the st
10920 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b atement that mak
10930 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c es them is compl
10940 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 eted (when the s
10950 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a tatement handle.
10960 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 ** is passed to
10970 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
10980 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 ] or [sqlite3_fi
10990 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a nalize()])..**.*
109a0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b * See also the [
109b0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
109c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 )] interface, th
109d0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e e.** [count_chan
109e0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 ges pragma], and
109f0 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e the [total_chan
10a00 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 ges() SQL functi
10a10 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 on]..**.** If a
10a20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
10a30 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e makes changes on
10a40 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
10a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
10a60 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
10a70 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
10a80 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
10a90 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 the value.** re
10aa0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 turned is unpred
10ab0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
10ac0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
10ad0 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c nt sqlite3_total
10ae0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
10af0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
10b00 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 REF: Interrupt A
10b10 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 Long-Running Qu
10b20 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ery.**.** ^This
10b30 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 function causes
10b40 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 any pending data
10b50 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 base operation t
10b60 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 o abort and.** r
10b70 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 eturn at its ear
10b80 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 liest opportunit
10b90 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 y. This routine
10ba0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 is typically.**
10bb0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e called in respon
10bc0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 se to a user act
10bd0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 ion such as pres
10be0 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a sing "Cancel".**
10bf0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 or Ctrl-C where
10c00 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 the user wants
10c10 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 a long query ope
10c20 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a ration to halt.*
10c30 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a * immediately..*
10c40 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 *.** ^It is safe
10c50 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f to call this ro
10c60 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 utine from a thr
10c70 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 ead different fr
10c80 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 om the.** thread
10c90 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 that is current
10ca0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 ly running the d
10cb0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
10cc0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 n. But it.** is
10cd0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c not safe to cal
10ce0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 l this routine w
10cf0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
10d00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
10d10 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 .** is closed or
10d20 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 might close bef
10d30 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 ore sqlite3_inte
10d40 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e rrupt() returns.
10d50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 .**.** ^If an SQ
10d60 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 L operation is v
10d70 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 ery nearly finis
10d80 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 hed at the time
10d90 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f when.** sqlite3_
10da0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 interrupt() is c
10db0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d alled, then it m
10dc0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e ight not have an
10dd0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 opportunity.**
10de0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 to be interrupte
10df0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 d and might cont
10e00 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 inue to completi
10e10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 on..**.** ^An SQ
10e20 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 L operation that
10e30 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 is interrupted
10e40 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c will return [SQL
10e50 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a ITE_INTERRUPT]..
10e60 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 ** ^If the inter
10e70 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 rupted SQL opera
10e80 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 tion is an INSER
10e90 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
10ea0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 LETE.** that is
10eb0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 inside an explic
10ec0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
10ed0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 then the entire
10ee0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 transaction.** w
10ef0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ill be rolled ba
10f00 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
10f10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
10f20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 ite3_interrupt(D
10f30 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 ) call is in eff
10f40 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 ect until all cu
10f50 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a rrently running.
10f60 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
10f70 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
10f80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d onnection] D com
10f90 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 plete. ^Any new
10fa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
10fb0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
10fc0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 ted after the sq
10fd0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
10fe0 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 ) call and befor
10ff0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e e the .** runnin
11000 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 g statements rea
11010 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e ches zero are in
11020 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 terrupted as if
11030 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a they had been.**
11040 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 running prior t
11050 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e o the sqlite3_in
11060 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 terrupt() call.
11070 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d ^New SQL statem
11080 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
11090 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
110a0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 he running state
110b0 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 ment count reach
110c0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e es zero are.** n
110d0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 ot effected by t
110e0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
110f0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 rupt()..** ^A ca
11100 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
11110 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 terrupt(D) that
11120 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 occurs when ther
11130 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 e are no running
11140 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
11150 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e ts is a no-op an
11160 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 d has no effect
11170 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 on SQL statement
11180 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
11190 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
111a0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
111b0 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 t() call returns
111c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 ..**.** If the d
111d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
111e0 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 on closes while
111f0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
11200 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e pt()].** is runn
11210 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 ing then bad thi
11220 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ngs will likely
11230 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 happen..*/.void
11240 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
11250 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a t(sqlite3*);../*
11260 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
11270 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 termine If An SQ
11280 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 L Statement Is C
11290 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 omplete.**.** Th
112a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
112b0 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 useful during c
112c0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 ommand-line inpu
112d0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 t to determine i
112e0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 f the.** current
112f0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 ly entered text
11300 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 seems to form a
11310 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
11320 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 tement or.** if
11330 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 additional input
11340 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 is needed befor
11350 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 e sending the te
11360 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 xt into.** SQLit
11370 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 e for parsing.
11380 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
11390 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 return 1 if the
113a0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 input string.**
113b0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 appears to be a
113c0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
113d0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 tement. ^A stat
113e0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 ement is judged
113f0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 to be.** complet
11400 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 e if it ends wit
11410 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f h a semicolon to
11420 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ken and is not a
11430 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 prefix of a.**
11440 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 well-formed CREA
11450 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 TE TRIGGER state
11460 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f ment. ^Semicolo
11470 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 ns that are embe
11480 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 dded within.** s
11490 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f tring literals o
114a0 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 r quoted identif
114b0 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d ier names or com
114c0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a ments are not.**
114d0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b independent tok
114e0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 ens (they are pa
114f0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 rt of the token
11500 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 in which they ar
11510 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 e.** embedded) a
11520 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 nd thus do not c
11530 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d ount as a statem
11540 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ent terminator.
11550 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 ^Whitespace.**
11560 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 and comments tha
11570 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e t follow the fin
11580 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 al semicolon are
11590 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
115a0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
115b0 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 return 0 if the
115c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 statement is inc
115d0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a omplete. ^If a.
115e0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
115f0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e tion fails, then
11600 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 SQLITE_NOMEM is
11610 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
11620 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
11630 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 do not parse th
11640 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
11650 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f thus.** will no
11660 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 t detect syntact
11670 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 ically incorrect
11680 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 SQL..**.** ^(If
11690 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 SQLite has not
116a0 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 been initialized
116b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
116c0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 initialize()] pr
116d0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b ior .** to invok
116e0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 ing sqlite3_comp
116f0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 lete16() then sq
11700 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
11710 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
11720 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 automatically b
11730 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 y sqlite3_comple
11740 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 te16(). If that
11750 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
11760 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 fails,.** then t
11770 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
11780 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d from sqlite3_com
11790 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 plete16() will b
117a0 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 e non-zero.** re
117b0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
117c0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 her or not the i
117d0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 nput SQL is comp
117e0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 lete.)^.**.** Th
117f0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 e input to [sqli
11800 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 te3_complete()]
11810 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 must be a zero-t
11820 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
11830 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a -8 string..**.**
11840 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
11850 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
11860 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 6()] must be a z
11870 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
11880 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 * UTF-16 string
11890 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
118a0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c rder..*/.int sql
118b0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f ite3_complete(co
118c0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a nst char *sql);.
118d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 int sqlite3_comp
118e0 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 lete16(const voi
118f0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d *sql);../*.**
11900 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 CAPI3REF: Regist
11910 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f er A Callback To
11920 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 Handle SQLITE_B
11930 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a USY Errors.**.**
11940 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 ^This routine s
11950 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ets a callback f
11960 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 unction that mig
11970 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 ht be invoked wh
11980 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 enever.** an att
11990 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 empt is made to
119a0 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 open a database
119b0 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 table that anoth
119c0 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 er thread.** or
119d0 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b process has lock
119e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
119f0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 e busy callback
11a00 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 is NULL, then [S
11a10 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
11a20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
11a30 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 CKED].** is retu
11a40 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 rned immediately
11a50 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 upon encounteri
11a60 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 ng the lock. ^I
11a70 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 f the busy callb
11a80 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 ack.** is not NU
11a90 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c LL, then the cal
11aa0 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 lback might be i
11ab0 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 nvoked with two
11ac0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a arguments..**.**
11ad0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
11ae0 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 ment to the busy
11af0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f handler is a co
11b00 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 py of the void*
11b10 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a pointer which.**
11b20 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 is the third ar
11b30 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
11b40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
11b50 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 . ^The second a
11b60 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 rgument to.** th
11b70 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 e busy handler c
11b80 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
11b90 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 umber of times t
11ba0 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e hat the busy han
11bb0 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e dler has.** been
11bc0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 invoked for thi
11bd0 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e s locking event.
11be0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 ^If the.** bus
11bf0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 y callback retur
11c00 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 ns 0, then no ad
11c10 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 ditional attempt
11c20 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a s are made to.**
11c30 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
11c40 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 base and [SQLITE
11c50 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
11c60 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
11c70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
11c80 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 ^If the callbac
11c90 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 k returns non-ze
11ca0 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 ro, then another
11cb0 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d attempt.** is m
11cc0 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 ade to open the
11cd0 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 database for rea
11ce0 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 ding and the cyc
11cf0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a le repeats..**.*
11d00 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f * The presence o
11d10 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 f a busy handler
11d20 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e does not guaran
11d30 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c tee that it will
11d40 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 be invoked.** w
11d50 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 hen there is loc
11d60 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 k contention. ^I
11d70 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 f SQLite determi
11d80 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e nes that invokin
11d90 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 g the busy.** ha
11da0 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 ndler could resu
11db0 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b lt in a deadlock
11dc0 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 , it will go ahe
11dd0 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 ad and return [S
11de0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f QLITE_BUSY].** o
11df0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
11e00 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 BLOCKED] instead
11e10 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 of invoking the
11e20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
11e30 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 * Consider a sce
11e40 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 nario where one
11e50 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
11e60 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 ng a read lock t
11e70 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 hat.** it is try
11e80 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 ing to promote t
11e90 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 o a reserved loc
11ea0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e k and.** a secon
11eb0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c d process is hol
11ec0 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 ding a reserved
11ed0 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 lock that it is
11ee0 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f trying.** to pro
11ef0 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 mote to an exclu
11f00 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 sive lock. The
11f10 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 first process ca
11f20 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 nnot proceed.**
11f30 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c because it is bl
11f40 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 ocked by the sec
11f50 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f ond and the seco
11f60 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f nd process canno
11f70 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 t.** proceed bec
11f80 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
11f90 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e ed by the first.
11fa0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 If both proces
11fb0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 ses.** invoke th
11fc0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c e busy handlers,
11fd0 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 neither will ma
11fe0 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e ke any progress.
11ff0 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 Therefore,.**
12000 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b SQLite returns [
12010 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 SQLITE_BUSY] for
12020 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
12030 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 ss, hoping that
12040 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 this.** will ind
12050 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 uce the first pr
12060 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 ocess to release
12070 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 its read lock a
12080 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 nd allow.** the
12090 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 second process t
120a0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a o proceed..**.**
120b0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 ^The default bu
120c0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e sy callback is N
120d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ULL..**.** ^The
120e0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 [SQLITE_BUSY] er
120f0 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 ror is converted
12100 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 to [SQLITE_IOER
12110 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 R_BLOCKED].** wh
12120 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 en SQLite is in
12130 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 the middle of a
12140 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f large transactio
12150 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a n where all the.
12160 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 ** changes will
12170 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 not fit into the
12180 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 in-memory cache
12190 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a . SQLite will.*
121a0 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 * already hold a
121b0 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f RESERVED lock o
121c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
121d0 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 ile, but it need
121e0 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 s.** to promote
121f0 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 this lock to EXC
12200 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 LUSIVE so that i
12210 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 t can spill cach
12220 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 e.** pages into
12230 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
12240 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 e without harm t
12250 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 o concurrent.**
12260 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 readers. ^If it
12270 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 is unable to pr
12280 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 omote the lock,
12290 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f then the in-memo
122a0 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c ry.** cache will
122b0 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 be left in an i
122c0 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 nconsistent stat
122d0 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 e and so the err
122e0 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 or.** code is pr
122f0 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 omoted from the
12300 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 relatively benig
12310 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 n [SQLITE_BUSY]
12320 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 to.** the more s
12330 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f evere [SQLITE_IO
12340 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e ERR_BLOCKED]. ^
12350 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 This error code
12360 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 promotion.** for
12370 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 ces an automatic
12380 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 rollback of the
12390 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 changes. See t
123a0 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f he.** <a href="/
123b0 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 cvstrac/wiki?p=C
123c0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 orruptionFollowi
123d0 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a ngBusyError">.**
123e0 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f CorruptionFollo
123f0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 wingBusyError</a
12400 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 > wiki page for
12410 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 a discussion of
12420 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 why.** this is i
12430 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 mportant..**.**
12440 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 ^(There can only
12450 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
12460 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 y handler define
12470 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 d for each.** [d
12480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
12490 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 on]. Setting a
124a0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 new busy handler
124b0 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 clears any.** p
124c0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 reviously set ha
124d0 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 ndler.)^ ^Note
124e0 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 that calling [sq
124f0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
12500 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c ut()].** will al
12510 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 so set or clear
12520 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
12530 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 ..**.** The busy
12540 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
12550 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 not take any ac
12560 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 tions which modi
12570 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 fy the.** databa
12580 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
12590 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
125a0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e usy handler. An
125b0 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a y such actions.*
125c0 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 * result in unde
125d0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
125e0 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 ** .** A busy ha
125f0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 ndler must not c
12600 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
12610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
12620 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 or [prepared sta
12630 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 tement] that inv
12640 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 oked the busy ha
12650 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ndler..*/.int sq
12660 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
12670 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
12680 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 (*)(void*,int),
12690 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
126a0 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 API3REF: Set A B
126b0 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a usy Timeout.**.*
126c0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
126d0 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f sets a [sqlite3_
126e0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 busy_handler | b
126f0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 usy handler] tha
12700 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 t sleeps.** for
12710 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 a specified amou
12720 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 nt of time when
12730 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 a table is locke
12740 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 d. ^The handler
12750 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d .** will sleep m
12760 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e ultiple times un
12770 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 til at least "ms
12780 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
12790 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 f sleeping.** ha
127a0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 ve accumulated.
127b0 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 ^After at least
127c0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
127d0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a ds of sleeping,.
127e0 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 ** the handler r
127f0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 eturns 0 which c
12800 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 auses [sqlite3_s
12810 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e tep()] to return
12820 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
12830 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
12840 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a RR_BLOCKED]..**.
12850 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 ** ^Calling this
12860 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e routine with an
12870 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 argument less t
12880 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 han or equal to
12890 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 zero.** turns of
128a0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c f all busy handl
128b0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ers..**.** ^(The
128c0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
128d0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
128e0 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 dler for a parti
128f0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
12900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
12910 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d ny any given mom
12920 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 ent. If another
12930 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a busy handler.**
12940 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 was defined (u
12950 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 sing [sqlite3_bu
12960 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 sy_handler()]) p
12970 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a rior to calling.
12980 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c ** this routine,
12990 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 that other busy
129a0 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 handler is clea
129b0 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 red.)^.*/.int sq
129c0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
129d0 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ut(sqlite3*, int
129e0 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ms);../*.** CAP
129f0 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e I3REF: Convenien
12a00 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 ce Routines For
12a10 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a Running Queries.
12a20 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e **.** Definition
12a30 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 : A <b>result ta
12a40 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 ble</b> is memor
12a50 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 y data structure
12a60 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a created by the.
12a70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ** [sqlite3_get_
12a80 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 table()] interfa
12a90 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 ce. A result ta
12aa0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a ble records the.
12ab0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 ** complete quer
12ac0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f y results from o
12ad0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 ne or more queri
12ae0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 es..**.** The ta
12af0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 ble conceptually
12b00 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 has a number of
12b10 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e rows and column
12b20 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 s. But.** these
12b30 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 numbers are not
12b40 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 part of the res
12b50 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 ult table itself
12b60 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 . These.** numb
12b70 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 ers are obtained
12b80 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 separately. Le
12b90 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 t N be the numbe
12ba0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 r of rows.** and
12bb0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 M be the number
12bc0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a of columns..**.
12bd0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
12be0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 e is an array of
12bf0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 pointers to zer
12c00 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
12c10 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 -8 strings..** T
12c20 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d here are (N+1)*M
12c30 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 elements in the
12c40 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 array. The fir
12c50 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f st M pointers po
12c60 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 int.** to zero-t
12c70 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
12c80 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 s that contain
12c90 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 the names of the
12ca0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 columns..** The
12cb0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 remaining entri
12cc0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 es all point to
12cd0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 query results.
12ce0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 NULL values resu
12cf0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f lt.** in NULL po
12d00 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 inters. All oth
12d10 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e er values are in
12d20 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 their UTF-8 zer
12d30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
12d40 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 string represent
12d50 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 ation as returne
12d60 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
12d70 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a lumn_text()]..**
12d80 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
12d90 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 le might consist
12da0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 of one or more
12db0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12dc0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 ns..** It is not
12dd0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 safe to pass a
12de0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 result table dir
12df0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 ectly to [sqlite
12e00 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 3_free()]..** A
12e10 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f result table sho
12e20 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 uld be deallocat
12e30 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
12e40 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 3_free_table()].
12e50 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 .**.** As an exa
12e60 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 mple of the resu
12e70 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c lt table format,
12e80 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 suppose a query
12e90 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 result.** is as
12ea0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
12eb0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
12ec0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 >.** Name
12ed0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a | Age.**
12ee0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d --------
12ef0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a ---------------.
12f00 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 ** Alice
12f10 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 | 43.**
12f20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 Bob
12f30 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 | 28.**
12f40 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 Cindy | 21
12f50 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
12f60 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
12f70 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 ere are two colu
12f80 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 mn (M==2) and th
12f90 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e ree rows (N==3).
12fa0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 Thus the.** re
12fb0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 sult table has 8
12fc0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f entries. Suppo
12fd0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 se the result ta
12fe0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a ble is stored.**
12ff0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d in an array nam
13000 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 es azResult. Th
13010 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 en azResult hold
13020 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a s this content:.
13030 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
13040 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
13050 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 azResult[0
13060 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 ] = "Name";.**
13070 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
13080 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 91;1] = "Age";.*
13090 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
130a0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 t[2] = "Alic
130b0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
130c0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 Result[3] =
130d0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "43";.**
130e0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 azResult[4]
130f0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 = "Bob";.**
13100 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
13110 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 5] = "28";.**
13120 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
13130 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 1;6] = "Cindy";.
13140 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
13150 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 lt[7] = "21"
13160 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
13170 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e ckquote>.**.** ^
13180 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
13190 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e table() function
131a0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f evaluates one o
131b0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f r more.** semico
131c0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 lon-separated SQ
131d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 L statements in
131e0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
131f0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 ted UTF-8.** str
13200 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 ing of its 2nd p
13210 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
13220 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 urns a result ta
13230 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f ble to the.** po
13240 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 inter given in i
13250 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ts 3rd parameter
13260 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 ..**.** After th
13270 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 e application ha
13280 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
13290 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 the result from
132a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
132b0 65 28 29 2c 0a 2a 2a 20 69 74 20 73 68 6f 75 6c e(),.** it shoul
132c0 64 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c d pass the resul
132d0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 t table pointer
132e0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f to sqlite3_free_
132f0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 table() in order
13300 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 to.** release t
13310 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 he memory that w
13320 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 as malloced. Be
13330 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 cause of the way
13340 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
13350 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 _malloc()] happe
13360 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 ns within sqlite
13370 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 3_get_table(), t
13380 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 he calling.** fu
13390 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 nction must not
133a0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c try to call [sql
133b0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 ite3_free()] dir
133c0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 ectly. Only.**
133d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
133e0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 ble()] is able t
133f0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 o release the me
13400 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e mory properly an
13410 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 d safely..**.**
13420 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 ^(The sqlite3_ge
13430 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 t_table() interf
13440 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 ace is implement
13450 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 ed as a wrapper
13460 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 around.** [sqlit
13470 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 e3_exec()]. The
13480 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
13490 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 le() routine doe
134a0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 s not have acces
134b0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 s.** to any inte
134c0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 rnal data struct
134d0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ures of SQLite.
134e0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 It uses only th
134f0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 e public.** inte
13500 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 rface defined he
13510 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 re. As a conseq
13520 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 uence, errors th
13530 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a at occur in the.
13540 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 ** wrapper layer
13550 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 outside of the
13560 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 internal [sqlite
13570 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 3_exec()] call a
13580 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 re not.** reflec
13590 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e ted in subsequen
135a0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 t calls to [sqli
135b0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f te3_errcode()] o
135c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 r.** [sqlite3_er
135d0 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e rmsg()].)^.*/.in
135e0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 t sqlite3_get_ta
135f0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ble(. sqlite3 *
13600 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 db, /*
13610 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
13620 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
13630 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 *zSql, /* S
13640 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 QL to be evaluat
13650 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a ed */. char ***
13660 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a pazResult, /*
13670 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 Results of the
13680 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a query */. int *
13690 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 pnRow,
136a0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
136b0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 sult rows writte
136c0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 n here */. int
136d0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 *pnColumn,
136e0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
136f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 esult columns wr
13700 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
13710 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 char **pzErrmsg
13720 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
13730 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
13740 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 */.);.void sqlit
13750 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 e3_free_table(ch
13760 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f ar **result);../
13770 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
13780 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 ormatted String
13790 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f Printing Functio
137a0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ns.**.** These r
137b0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b outines are work
137c0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 -alikes of the "
137d0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 printf()" family
137e0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a of functions.**
137f0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
13800 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
13810 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
13820 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
13830 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
13840 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
13850 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
13860 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
13870 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
13880 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
13890 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
138a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
138b0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
138c0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
138d0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
138e0 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 free()]. ^Both
138f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
13900 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
13910 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
13920 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
13930 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
13940 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
13950 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
13960 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
13970 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 5f ** ^(In sqlite3_
13980 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 snprintf() routi
13990 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ne is similar to
139a0 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 "snprintf()" fr
139b0 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 om.** the standa
139c0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 rd C library. T
139d0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 he result is wri
139e0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a tten into the.**
139f0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 buffer supplied
13a00 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
13a10 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 arameter whose s
13a20 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a ize is given by.
13a30 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 ** the first par
13a40 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 ameter. Note tha
13a50 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 t the order of t
13a60 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 he.** first two
13a70 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 parameters is re
13a80 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 versed from snpr
13a90 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 intf().)^ This
13aa0 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 is an.** histori
13ab0 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 cal accident tha
13ac0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 t cannot be fixe
13ad0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 d without breaki
13ae0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 ng.** backwards
13af0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 compatibility.
13b00 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 ^(Note also that
13b10 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
13b20 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 f().** returns a
13b30 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 pointer to its
13b40 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f buffer instead o
13b50 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a f the number of.
13b60 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 ** characters ac
13b70 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 tually written i
13b80 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 nto the buffer.)
13b90 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ^ We admit that
13ba0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
13bb0 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 f characters wri
13bc0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 tten would be a
13bd0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 more useful retu
13be0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 rn.** value but
13bf0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 we cannot change
13c00 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
13c10 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 ion of sqlite3_s
13c20 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 nprintf().** now
13c30 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e without breakin
13c40 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e g compatibility.
13c50 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 .**.** ^As long
13c60 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 as the buffer si
13c70 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 ze is greater th
13c80 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 an zero, sqlite3
13c90 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 _snprintf().** g
13ca0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
13cb0 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 he buffer is alw
13cc0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
13cd0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ted. ^The first
13ce0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e .** parameter "n
13cf0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 " is the total s
13d00 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
13d10 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 r, including spa
13d20 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 ce for.** the ze
13d30 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 ro terminator.
13d40 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 So the longest s
13d50 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 tring that can b
13d60 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 e completely.**
13d70 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 written will be
13d80 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a n-1 characters..
13d90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
13da0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 ines all impleme
13db0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e nt some addition
13dc0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a al formatting.**
13dd0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 options that ar
13de0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e e useful for con
13df0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 structing SQL st
13e00 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c atements..** All
13e10 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 of the usual pr
13e20 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e intf() formattin
13e30 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e g options apply.
13e40 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 In addition, t
13e50 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 here.** is are "
13e60 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 %q", "%Q", and "
13e70 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a %z" options..**.
13e80 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 ** ^(The %q opti
13e90 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 on works like %s
13ea0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 in that it subs
13eb0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 titutes a null-t
13ec0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
13ed0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 ing from the arg
13ee0 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 ument list. But
13ef0 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 %q also doubles
13f00 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 every '\'' char
13f10 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 acter..** %q is
13f20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 designed for use
13f30 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 inside a string
13f40 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 literal.)^ By
13f50 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c doubling each '\
13f60 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 ''.** character
13f70 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 it escapes that
13f80 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c character and al
13f90 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e lows it to be in
13fa0 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 serted into.** t
13fb0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a he string..**.**
13fc0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 For example, as
13fd0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 sume the string
13fe0 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 variable zText c
13ff0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 ontains text as
14000 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
14010 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
14020 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 .** char *zText
14030 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 = "It's a happy
14040 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 day!";.** </pre
14050 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
14060 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 *.** One can use
14070 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e this text in an
14080 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
14090 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
140a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
140b0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 e>.** char *zSQ
140c0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 L = sqlite3_mpri
140d0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f ntf("INSERT INTO
140e0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 table VALUES('%
140f0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a q')", zText);.**
14100 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 sqlite3_exec(d
14110 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 b, zSQL, 0, 0, 0
14120 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 );.** sqlite3_f
14130 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f ree(zSQL);.** </
14140 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
14150 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 >.**.** Because
14160 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 the %q format st
14170 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 ring is used, th
14180 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 e '\'' character
14190 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 in zText.** is
141a0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 escaped and the
141b0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 SQL generated is
141c0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
141d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
141e0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 pre>.** INSERT
141f0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
14200 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 ES('It''s a happ
14210 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 y day!').** </pr
14220 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
14230 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f **.** This is co
14240 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 rrect. Had we u
14250 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f sed %s instead o
14260 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 f %q, the genera
14270 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 ted SQL.** would
14280 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b have looked lik
14290 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 e this:.**.** <b
142a0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
142b0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
142c0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
142d0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
142e0 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 ');.** </pre></b
142f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
14300 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 This second exa
14310 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 mple is an SQL s
14320 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 yntax error. As
14330 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 a general rule
14340 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c you should.** al
14350 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 ways use %q inst
14360 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 ead of %s when i
14370 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e nserting text in
14380 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 to a string lite
14390 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ral..**.** ^(The
143a0 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %Q option works
143b0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 like %q except
143c0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e it also adds sin
143d0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e gle quotes aroun
143e0 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 d.** the outside
143f0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 of the total st
14400 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 ring. Additiona
14410 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 lly, if the para
14420 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 meter in the.**
14430 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 argument list is
14440 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
14450 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 %Q substitutes
14460 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 the text "NULL"
14470 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 (without.** sing
14480 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 le quotes).)^ S
14490 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 o, for example,
144a0 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a one could say:.*
144b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
144c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
144d0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
144e0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
144f0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
14500 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a S(%Q)", zText);.
14510 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
14520 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
14530 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
14540 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
14550 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
14560 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f te>.**.** The co
14570 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 de above will re
14580 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 nder a correct S
14590 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
145a0 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 the zSQL.** vari
145b0 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 able even if the
145c0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 zText variable
145d0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
145e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 r..**.** ^(The "
145f0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f %z" formatting o
14600 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
14610 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 "%s" but with t
14620 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 he.** addition t
14630 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 hat after the st
14640 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 ring has been re
14650 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e ad and copied in
14660 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 to.** the result
14670 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
14680 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 )] is called on
14690 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
146a0 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c .)^.*/.char *sql
146b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e ite3_mprintf(con
146c0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 st char*,...);.c
146d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 har *sqlite3_vmp
146e0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 rintf(const char
146f0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 *, va_list);.cha
14700 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 r *sqlite3_snpri
14710 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
14720 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b nst char*, ...);
14730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
14740 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
14750 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a ion Subsystem.**
14760 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
14770 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 ore uses these t
14780 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hree routines fo
14790 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e r all of its own
147a0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d .** internal mem
147b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
147c0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 eeds. "Core" in
147d0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
147e0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f tence.** does no
147f0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 t include operat
14800 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
14810 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e fic VFS implemen
14820 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 tation. The.**
14830 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 Windows VFS uses
14840 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 native malloc()
14850 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 and free() for
14860 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e some operations.
14870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
14880 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 te3_malloc() rou
14890 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
148a0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 ointer to a bloc
148b0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 k.** of memory a
148c0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
148d0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 in length, where
148e0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 N is the parame
148f0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ter..** ^If sqli
14900 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
14910 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e unable to obtain
14920 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 sufficient free
14930 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 .** memory, it r
14940 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
14950 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 inter. ^If the
14960 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
14970 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
14980 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
14990 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
149a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
149b0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
149c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 ointer..**.** ^C
149d0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 alling sqlite3_f
149e0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 ree() with a poi
149f0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 nter previously
14a00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
14a10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
14a20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
14a30 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 oc() releases th
14a40 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 at memory so.**
14a50 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 that it might be
14a60 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 reused. ^The s
14a70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f qlite3_free() ro
14a80 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f utine is.** a no
14a90 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 -op if is called
14aa0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
14ab0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 nter. Passing a
14ac0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
14ad0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
14ae0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 () is harmless.
14af0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 After being fre
14b00 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 ed, memory.** sh
14b10 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 ould neither be
14b20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e read nor written
14b30 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 . Even reading
14b40 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 previously freed
14b50 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 .** memory might
14b60 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 result in a seg
14b70 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 mentation fault
14b80 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 or other severe
14b90 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 error..** Memory
14ba0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 corruption, a s
14bb0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
14bc0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 t, or other seve
14bd0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 re error.** migh
14be0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 t result if sqli
14bf0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 te3_free() is ca
14c00 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d lled with a non-
14c10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 NULL pointer tha
14c20 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 t.** was not obt
14c30 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 ained from sqlit
14c40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
14c50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
14c60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
14c70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
14c80 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
14c90 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
14ca0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
14cb0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 llocation to be
14cc0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
14cd0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
14ce0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
14cf0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 eter. The memor
14d00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
14d10 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 be resized is th
14d20 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
14d30 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 eter.)^ ^ If the
14d40 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
14d50 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
14d60 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 loc().** is a NU
14d70 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
14d80 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 its behavior is
14d90 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c identical to cal
14da0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
14db0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 malloc(N) where
14dc0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
14dd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
14de0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
14df0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e ** ^If the secon
14e00 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
14e10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
14e20 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e is zero or.** n
14e30 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 egative then the
14e40 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 behavior is exa
14e50 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 ctly the same as
14e60 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
14e70 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 te3_free(P) wher
14e80 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 e P is the first
14e90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
14ea0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
14eb0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 .** ^sqlite3_rea
14ec0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 lloc() returns a
14ed0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 pointer to a me
14ee0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
14ef0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e ** of at least N
14f00 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f bytes in size o
14f10 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 r NULL if suffic
14f20 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 ient memory is u
14f30 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e navailable..** ^
14f40 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 If M is the size
14f50 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c of the prior al
14f60 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d location, then m
14f70 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a in(N,M) bytes.**
14f80 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c of the prior al
14f90 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 location are cop
14fa0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 ied into the beg
14fb0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 inning of buffer
14fc0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 returned.** by
14fd0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
14fe0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 ) and the prior
14ff0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 allocation is fr
15000 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 eed..** ^If sqli
15010 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
15020 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e turns NULL, then
15030 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
15040 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 ation.** is not
15050 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 freed..**.** ^Th
15060 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 e memory returne
15070 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c d by sqlite3_mal
15080 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 loc() and sqlite
15090 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 3_realloc().** i
150a0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 s always aligned
150b0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 to at least an
150c0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 8 byte boundary.
150d0 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 .**.** In SQLite
150e0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 version 3.5.0 a
150f0 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 nd 3.5.1, it was
15100 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 possible to def
15110 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 ine.** the SQLIT
15120 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c E_OMIT_MEMORY_AL
15130 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 LOCATION which w
15140 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 ould cause the b
15150 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 uilt-in.** imple
15160 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
15170 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 se routines to b
15180 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 e omitted. That
15190 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
151a0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 s no longer prov
151b0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c ided. Only buil
151c0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
151d0 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 cators can be us
151e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 ed..**.** The Wi
151f0 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 ndows OS interfa
15200 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a ce layer calls.*
15210 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c * the system mal
15220 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
15230 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 directly when c
15240 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c onverting.** fil
15250 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 enames between t
15260 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e he UTF-8 encodin
15270 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 g used by SQLite
15280 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 .** and whatever
15290 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 filename encodi
152a0 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 ng is used by th
152b0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e e particular Win
152c0 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 dows.** installa
152d0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c tion. Memory al
152e0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 location errors
152f0 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 are detected, bu
15300 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 t.** they are re
15310 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b ported back as [
15320 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
15330 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 or.** [SQLITE_I
15340 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 OERR] rather tha
15350 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d n [SQLITE_NOMEM]
15360 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e ..**.** The poin
15370 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ter arguments to
15380 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
15390 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
153a0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 ealloc()].** mus
153b0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c t be either NULL
153c0 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 or else pointer
153d0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 s obtained from
153e0 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 a prior.** invoc
153f0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
15400 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 3_malloc()] or [
15410 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
15420 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 )] that have.**
15430 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c not yet been rel
15440 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eased..**.** The
15450 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
15460 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 t not read or wr
15470 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a ite any part of.
15480 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 ** a block of me
15490 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 mory after it ha
154a0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 s been released
154b0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
154c0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 3_free()] or [sq
154d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
154e0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
154f0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a e3_malloc(int);.
15500 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 void *sqlite3_re
15510 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 alloc(void*, int
15520 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
15530 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a free(void*);../*
15540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
15550 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 mory Allocator S
15560 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 tatistics.**.**
15570 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 SQLite provides
15580 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 these two interf
15590 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 aces for reporti
155a0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 ng on the status
155b0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
155c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b te3_malloc()], [
155d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c sqlite3_free()],
155e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
155f0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 alloc()].** rout
15600 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d ines, which form
15610 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 the built-in me
15620 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
15630 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a subsystem..**.**
15640 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d ^The [sqlite3_m
15650 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f emory_used()] ro
15660 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
15670 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
15680 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 s.** of memory c
15690 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e urrently outstan
156a0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 ding (malloced b
156b0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a ut not freed)..*
156c0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
156d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
156e0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
156f0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a rns the maximum.
15700 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c ** value of [sql
15710 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
15720 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 ()] since the hi
15730 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
15740 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e was last reset.
15750 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 ^The values re
15760 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
15770 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
15780 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
15790 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
157a0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e er()] include an
157b0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 y overhead.** ad
157c0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e ded by SQLite in
157d0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 its implementat
157e0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
157f0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 malloc()],.** bu
15800 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 t not overhead a
15810 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 dded by the any
15820 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 underlying syste
15830 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 m library.** rou
15840 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 tines that [sqli
15850 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 te3_malloc()] ma
15860 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 y call..**.** ^T
15870 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 he memory high-w
15880 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 ater mark is res
15890 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e et to the curren
158a0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 t value of.** [s
158b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
158c0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c ed()] if and onl
158d0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 y if the paramet
158e0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
158f0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
15900 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 er()] is true.
15910 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 ^The value retur
15920 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 ned.** by [sqlit
15930 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
15940 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 ter(1)] is the h
15950 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
15960 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 * prior to the r
15970 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 eset..*/.sqlite3
15980 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d _int64 sqlite3_m
15990 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 emory_used(void)
159a0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 ;.sqlite3_int64
159b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
159c0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 ighwater(int res
159d0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 etFlag);../*.**
159e0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f CAPI3REF: Pseudo
159f0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 -Random Number G
15a00 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 enerator.**.** S
15a10 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 QLite contains a
15a20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 high-quality ps
15a30 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 eudo-random numb
15a40 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 er generator (PR
15a50 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 NG) used to.** s
15a60 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f elect random [RO
15a70 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 WID | ROWIDs] wh
15a80 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 en inserting new
15a90 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 records into a
15aa0 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c table that.** al
15ab0 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c ready uses the l
15ac0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 argest possible
15ad0 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 [ROWID]. The PR
15ae0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 NG is also used
15af0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 for.** the build
15b00 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 -in random() and
15b10 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 randomblob() SQ
15b20 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 L functions. Th
15b30 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
15b40 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 ows.** applicati
15b50 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 ons to access th
15b60 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 e same PRNG for
15b70 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a other purposes..
15b80 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f **.** ^A call to
15b90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 this routine st
15ba0 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 ores N bytes of
15bb0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
15bc0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 buffer P..**.**
15bd0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 ^The first time
15be0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
15bf0 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 invoked (either
15c00 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 internally or by
15c10 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
15c20 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 ion) the PRNG is
15c30 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 seeded using ra
15c40 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 ndomness obtaine
15c50 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 d.** from the xR
15c60 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 andomness method
15c70 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 of the default
15c80 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
15c90 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c ject..** ^On all
15ca0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f subsequent invo
15cb0 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 cations, the pse
15cc0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
15cd0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 s generated.** i
15ce0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 nternally and wi
15cf0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 thout recourse t
15d00 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
15d10 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a fs] xRandomness.
15d20 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f ** method..*/.vo
15d30 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f id sqlite3_rando
15d40 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 mness(int N, voi
15d50 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d *P);../*.** CA
15d60 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d PI3REF: Compile-
15d70 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 Time Authorizati
15d80 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a on Callbacks.**.
15d90 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
15da0 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74 registers a aut
15db0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
15dc0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c with a particul
15dd0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ar.** [database
15de0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 connection], sup
15df0 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 plied in the fir
15e00 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 st argument..**
15e10 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ^The authorizer
15e20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
15e30 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 ked as SQL state
15e40 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 ments are being
15e50 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b compiled.** by [
15e60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
15e70 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
15e80 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ts [sqlite3_prep
15e90 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 are_v2()],.** [s
15ea0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
15eb0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
15ec0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
15ed0 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a . ^At various.*
15ee0 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 * points during
15ef0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 the compilation
15f00 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 process, as logi
15f10 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 c is being creat
15f20 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d ed.** to perform
15f30 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 various actions
15f40 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 , the authorizer
15f50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
15f60 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 oked to.** see i
15f70 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 f those actions
15f80 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 are allowed. ^T
15f90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
15fa0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a llback should.**
15fb0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
15fc0 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 OK] to allow the
15fd0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 action, [SQLITE
15fe0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 _IGNORE] to disa
15ff0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 llow the.** spec
16000 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 ific action but
16010 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 allow the SQL st
16020 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 atement to conti
16030 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d nue to be.** com
16040 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 piled, or [SQLIT
16050 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 E_DENY] to cause
16060 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 the entire SQL
16070 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a statement to be.
16080 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 ** rejected with
16090 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 an error. ^If
160a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
160b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a allback returns.
160c0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 ** any value oth
160d0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
160e0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 IGNORE], [SQLITE
160f0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 _OK], or [SQLITE
16100 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 _DENY].** then t
16110 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 he [sqlite3_prep
16120 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 are_v2()] or equ
16130 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 ivalent call tha
16140 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 t triggered.** t
16150 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 he authorizer wi
16160 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 ll fail with an
16170 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a error message..*
16180 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 *.** When the ca
16190 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
161a0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 SQLITE_OK], that
161b0 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 means the opera
161c0 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 tion.** requeste
161d0 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 d is ok. ^When
161e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
161f0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e urns [SQLITE_DEN
16200 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 Y], the.** [sqli
16210 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
16220 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 ] or equivalent
16230 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
16240 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f red the.** autho
16250 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 rizer will fail
16260 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 with an error me
16270 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 ssage explaining
16280 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 that.** access
16290 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a is denied. .**.*
162a0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 * ^The first par
162b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
162c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
162d0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 k is a copy of t
162e0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 he third.** para
162f0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
16300 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
16310 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e zer() interface.
16320 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
16330 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ameter.** to the
16340 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
16350 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f integer [SQLITE_
16360 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f COPY | action co
16370 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 de] that specifi
16380 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 es.** the partic
16390 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 ular action to b
163a0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 e authorized. ^T
163b0 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 he third through
163c0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 sixth parameter
163d0 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c s.** to the call
163e0 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 back are zero-te
163f0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 rminated strings
16400 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 that contain ad
16410 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 ditional.** deta
16420 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 ils about the ac
16430 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f tion to be autho
16440 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 rized..**.** ^If
16450 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 the action code
16460 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 is [SQLITE_READ
16470 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c ].** and the cal
16480 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
16490 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 QLITE_IGNORE] th
164a0 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 en the.** [prepa
164b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 red statement] s
164c0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 tatement is cons
164d0 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 tructed to subst
164e0 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 itute.** a NULL
164f0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f value in place o
16500 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 f the table colu
16510 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 mn that would ha
16520 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 ve.** been read
16530 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 if [SQLITE_OK] h
16540 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 ad been returned
16550 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 . The [SQLITE_I
16560 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e GNORE].** return
16570 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
16580 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 deny an untruste
16590 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f d user access to
165a0 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 individual.** c
165b0 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c olumns of a tabl
165c0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 e..** ^If the ac
165d0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 tion code is [SQ
165e0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 LITE_DELETE] and
165f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
16600 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 turns.** [SQLITE
16610 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
16620 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 e [DELETE] opera
16630 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 tion proceeds bu
16640 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 t the.** [trunca
16650 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d te optimization]
16660 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 is disabled and
16670 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 all rows are de
16680 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c leted individual
16690 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 ly..**.** An aut
166a0 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 horizer is used
166b0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 when [sqlite3_pr
166c0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e epare | preparin
166d0 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d g].** SQL statem
166e0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 ents from an unt
166f0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 rusted source, t
16700 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 o ensure that th
16710 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
16720 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 .** do not try t
16730 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 o access data th
16740 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 ey are not allow
16750 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 ed to see, or th
16760 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
16770 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 * try to execute
16780 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 malicious state
16790 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 ments that damag
167a0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 e the database.
167b0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c For.** example,
167c0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
167d0 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 may allow a user
167e0 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 to enter arbitr
167f0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 ary.** SQL queri
16800 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f es for evaluatio
16810 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e n by a database.
16820 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 But the applic
16830 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f ation does.** no
16840 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 t want the user
16850 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 to be able to ma
16860 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 ke arbitrary cha
16870 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 nges to the.** d
16880 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 atabase. An aut
16890 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 horizer could th
168a0 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 en be put in pla
168b0 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 ce while the.**
168c0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c user-entered SQL
168d0 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 is being [sqlit
168e0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 e3_prepare | pre
168f0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 pared] that.** d
16900 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 isallows everyth
16910 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 ing except [SELE
16920 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a CT] statements..
16930 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
16940 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 ns that need to
16950 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d process SQL from
16960 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
16970 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f es.** might also
16980 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 consider loweri
16990 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 ng resource limi
169a0 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ts using [sqlite
169b0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 3_limit()].** an
169c0 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 d limiting datab
169d0 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 ase size using t
169e0 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 he [max_page_cou
169f0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 nt] [PRAGMA].**
16a00 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 in addition to u
16a10 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a sing an authoriz
16a20 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 er..**.** ^(Only
16a30 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 a single author
16a40 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 izer can be in p
16a50 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 lace on a databa
16a60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
16a70 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 at a time. Eac
16a80 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 h call to sqlite
16a90 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
16aa0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a overrides the.*
16ab0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e * previous call.
16ac0 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 )^ ^Disable the
16ad0 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 authorizer by i
16ae0 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c nstalling a NULL
16af0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 callback..** Th
16b00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 e authorizer is
16b10 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
16b20 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ult..**.** The a
16b30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
16b40 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 ck must not do a
16b50 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
16b60 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
16b70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
16b80 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
16b90 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
16ba0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 callback..** Not
16bb0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
16bc0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
16bd0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
16be0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
16bf0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
16c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
16c10 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
16c20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
16c30 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
16c40 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 * ^When [sqlite3
16c50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 _prepare_v2()] i
16c60 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 s used to prepar
16c70 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 e a statement, t
16c80 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 he.** statement
16c90 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 might be re-prep
16ca0 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c ared during [sql
16cb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 ite3_step()] due
16cc0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 to a .** schema
16cd0 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c change. Hence,
16ce0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
16cf0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 should ensure t
16d00 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 hat the.** corre
16d10 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 ct authorizer ca
16d20 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 llback remains i
16d30 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 n place during t
16d40 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
16d50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 ()]..**.** ^Note
16d60 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 that the author
16d70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
16d80 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 invoked only du
16d90 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ring.** [sqlite3
16da0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
16db0 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 ts variants. Au
16dc0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e thorization is n
16dd0 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 ot.** performed
16de0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 during statement
16df0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b evaluation in [
16e00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c sqlite3_step()],
16e10 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 unless.** as st
16e20 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 ated in the prev
16e30 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 ious paragraph,
16e40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
16e50 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 nvokes.** sqlite
16e60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 3_prepare_v2() t
16e70 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 o reprepare a st
16e80 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 atement after a
16e90 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a schema change..*
16ea0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 /.int sqlite3_se
16eb0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 t_authorizer(.
16ec0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 sqlite3*,. int
16ed0 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 (*xAuth)(void*,i
16ee0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 nt,const char*,c
16ef0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
16f00 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
16f10 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 r*),. void *pUs
16f20 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a erData.);../*.**
16f30 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f CAPI3REF: Autho
16f40 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 rizer Return Cod
16f50 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 es.**.** The [sq
16f60 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
16f70 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 izer | authorize
16f80 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 r callback funct
16f90 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 ion] must.** ret
16fa0 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 urn either [SQLI
16fb0 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 TE_OK] or one of
16fc0 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 these two const
16fd0 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a ants in order.**
16fe0 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 to signal SQLit
16ff0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 e whether or not
17000 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 the action is p
17010 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 ermitted. See t
17020 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 he.** [sqlite3_s
17030 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 et_authorizer |
17040 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d authorizer docum
17050 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 entation] for ad
17060 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f ditional.** info
17070 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 rmation..*/.#def
17080 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 ine SQLITE_DENY
17090 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 1 /* Abort t
170a0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
170b0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a with an error *
170c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
170d0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 _IGNORE 2 /* D
170e0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 on't allow acces
170f0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e s, but don't gen
17100 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a erate an error *
17110 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
17120 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 F: Authorizer Ac
17130 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a tion Codes.**.**
17140 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
17150 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
17160 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
17170 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
17180 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 unction.** that
17190 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 is invoked to au
171a0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 thorize certain
171b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
171c0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
171d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
171e0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
171f0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
17200 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
17210 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
17220 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
17230 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
17240 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
17250 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
17260 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
17270 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
17280 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
17290 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
172a0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
172b0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
172c0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a ration is to be.
172d0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ** authorized.
172e0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
172f0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
17300 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a e authorization.
17310 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
17320 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 tion will be par
17330 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 ameters or NULL
17340 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 depending on whi
17350 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 ch of these.** c
17360 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 odes is used as
17370 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
17380 65 74 65 72 2e 20 20 5e 54 68 65 20 35 74 68 20 eter. ^The 5th
17390 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
173a0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 .** authorizer c
173b0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
173c0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
173d0 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 ase ("main", "te
173e0 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 mp",.** etc.) if
173f0 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 5e 54 applicable. ^T
17400 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 he 6th parameter
17410 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
17420 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 er callback.** i
17430 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
17440 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 e inner-most tri
17450 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 gger or view tha
17460 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 t is responsible
17470 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 for.** the acce
17480 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 ss attempt or NU
17490 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 LL if this acces
174a0 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 s attempt is dir
174b0 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f ectly from.** to
174c0 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 p-level SQL code
174d0 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ..*/./**********
174e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
174f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
17500 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 3rd **********
17510 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a ** 4th *********
17520 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 **/.#define SQLI
17530 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 TE_CREATE_INDEX
17540 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 1 /*
17550 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
17560 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
17570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17580 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 E_CREATE_TABLE
17590 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 2 /* T
175a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
175b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
175c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
175d0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 _CREATE_TEMP_IND
175e0 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e EX 3 /* In
175f0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
17600 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
17610 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17620 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c CREATE_TEMP_TABL
17630 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 E 4 /* Tab
17640 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
17650 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
17660 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
17670 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 REATE_TEMP_TRIGG
17680 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 ER 5 /* Trig
17690 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
176a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
176b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
176c0 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 EATE_TEMP_VIEW
176d0 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 6 /* View
176e0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
176f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
17700 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
17710 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 ATE_TRIGGER
17720 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 7 /* Trigge
17730 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
17740 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
17750 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
17760 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 TE_VIEW
17770 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 8 /* View Na
17780 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
17790 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
177a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 ine SQLITE_DELET
177b0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
177c0 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 9 /* Table Na
177d0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
177e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
177f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 ne SQLITE_DROP_I
17800 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 NDEX 1
17810 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 0 /* Index Nam
17820 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
17830 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
17840 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 e SQLITE_DROP_TA
17850 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 BLE 11
17860 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
17870 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
17880 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
17890 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
178a0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 P_INDEX 12
178b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
178c0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
178d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
178e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
178f0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 _TABLE 13
17900 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
17910 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
17920 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
17930 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
17940 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 TRIGGER 14
17950 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
17960 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
17970 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17980 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 LITE_DROP_TEMP_V
17990 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f IEW 15 /
179a0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
179b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
179c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
179d0 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 ITE_DROP_TRIGGER
179e0 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 16 /*
179f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
17a00 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
17a10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17a20 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 TE_DROP_VIEW
17a30 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 17 /*
17a40 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
17a50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
17a60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17a70 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 E_INSERT
17a80 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 18 /* T
17a90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
17aa0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
17ab0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17ac0 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 _PRAGMA
17ad0 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 19 /* Pr
17ae0 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 agma Name 1s
17af0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f t arg or NULL */
17b00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17b10 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 READ
17b20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 20 /* Tab
17b30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
17b40 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
17b50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
17b60 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 ELECT
17b70 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 21 /* NULL
17b80 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
17b90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
17ba0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
17bb0 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 ANSACTION
17bc0 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 22 /* Opera
17bd0 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 tion NULL
17be0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
17bf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 efine SQLITE_UPD
17c00 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ATE
17c10 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 23 /* Table
17c20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e Name Column
17c30 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
17c40 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 fine SQLITE_ATTA
17c50 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
17c60 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 24 /* Filenam
17c70 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 e NULL
17c80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
17c90 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 ine SQLITE_DETAC
17ca0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
17cb0 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 25 /* Database
17cc0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 Name NULL
17cd0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
17ce0 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f ne SQLITE_ALTER_
17cf0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 TABLE 2
17d00 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6 /* Database
17d10 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d Name Table Nam
17d20 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
17d30 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 e SQLITE_REINDEX
17d40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 27
17d50 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
17d60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
17d70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
17d80 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 SQLITE_ANALYZE
17d90 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 28
17da0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
17db0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
17dc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
17dd0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 SQLITE_CREATE_VT
17de0 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 ABLE 29
17df0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
17e00 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 Module Name
17e10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
17e20 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c QLITE_DROP_VTABL
17e30 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 E 30
17e40 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
17e50 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
17e60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17e70 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 LITE_FUNCTION
17e80 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 31 /
17e90 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
17ea0 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 Function Name
17eb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
17ec0 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 ITE_SAVEPOINT
17ed0 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 32 /*
17ee0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 Operation
17ef0 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 Savepoint Name
17f00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17f10 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 TE_COPY
17f20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 0 /*
17f30 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a No longer used *
17f40 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
17f50 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 F: Tracing And P
17f60 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f rofiling Functio
17f70 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ns.** EXPERIMENT
17f80 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 AL.**.** These r
17f90 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 outines register
17fa0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
17fb0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 ons that can be
17fc0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 used for.** trac
17fd0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e ing and profilin
17fe0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 g the execution
17ff0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 of SQL statement
18000 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 s..**.** ^The ca
18010 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
18020 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 registered by sq
18030 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 lite3_trace() is
18040 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 invoked at.** v
18050 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 arious times whe
18060 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
18070 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 nt is being run
18080 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 by [sqlite3_step
18090 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ()]..** ^The sql
180a0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c ite3_trace() cal
180b0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
180c0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 with a UTF-8 re
180d0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a ndering of the.*
180e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 * SQL statement
180f0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 text as the stat
18100 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 ement first begi
18110 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a ns executing..**
18120 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 ^(Additional sq
18130 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 lite3_trace() ca
18140 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 llbacks might oc
18150 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 cur.** as each t
18160 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 riggered subprog
18170 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 ram is entered.
18180 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 The callbacks f
18190 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 or triggers.** c
181a0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 ontain a UTF-8 S
181b0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 QL comment that
181c0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 identifies the t
181d0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 rigger.)^.**.**
181e0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
181f0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
18200 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f d by sqlite3_pro
18210 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 file() is invoke
18220 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c d.** as each SQL
18230 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 statement finis
18240 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 hes. ^The profi
18250 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 le callback cont
18260 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 ains.** the orig
18270 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 inal statement t
18280 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d ext and an estim
18290 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 ate of wall-cloc
182a0 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 k time.** of how
182b0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 long that state
182c0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e ment took to run
182d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 ..*/.SQLITE_EXPE
182e0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 RIMENTAL void *s
182f0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
18300 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 ite3*, void(*xTr
18310 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
18320 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
18330 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
18340 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 NTAL void *sqlit
18350 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 e3_profile(sqlit
18360 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 e3*,. void(*xP
18370 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f rofile)(void*,co
18380 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 nst char*,sqlite
18390 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 3_uint64), void*
183a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
183b0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 EF: Query Progre
183c0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a ss Callbacks.**.
183d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
183e0 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 configures a ca
183f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
18400 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 - the.** progres
18410 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 s callback - tha
18420 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 t is invoked per
18430 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 iodically during
18440 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 long.** running
18450 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
18460 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c e3_exec()], [sql
18470 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 ite3_step()] and
18480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 .** [sqlite3_get
18490 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 _table()]. An e
184a0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 xample use for t
184b0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 his.** interface
184c0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 is to keep a GU
184d0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 I updated during
184e0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a a large query..
184f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 **.** ^If the pr
18500 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
18510 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
18520 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 , the operation
18530 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 is.** interrupte
18540 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 d. This feature
18550 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
18560 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 implement a.** "
18570 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f Cancel" button o
18580 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 n a GUI progress
18590 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a dialog box..**.
185a0 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 ** The progress
185b0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 handler must not
185c0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
185d0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
185e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
185f0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
18600 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 voked the progre
18610 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e ss handler..** N
18620 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 ote that [sqlite
18630 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
18640 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
18650 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 p()] both modify
18660 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 their.** databa
18670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 se connections f
18680 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f or the meaning o
18690 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 f "modify" in th
186a0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a is paragraph..**
186b0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
186c0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
186d0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c r(sqlite3*, int,
186e0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 int(*)(void*),
186f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
18700 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 API3REF: Opening
18710 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 A New Database
18720 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a Connection.**.**
18730 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
18740 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 open an SQLite
18750 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 database file wh
18760 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 ose name is give
18770 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 n by the.** file
18780 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e name argument. ^
18790 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 The filename arg
187a0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 ument is interpr
187b0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f eted as UTF-8 fo
187c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 r.** sqlite3_ope
187d0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
187e0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 open_v2() and as
187f0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
18800 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 ative byte.** or
18810 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f der for sqlite3_
18820 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 open16(). ^(A [d
18830 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
18840 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 on] handle is us
18850 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 ually.** returne
18860 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e d in *ppDb, even
18870 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 if an error occ
18880 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 urs. The only e
18890 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 xception is that
188a0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 .** if SQLite is
188b0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
188c0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f ate memory to ho
188d0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d ld the [sqlite3]
188e0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 object,.** a NU
188f0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 LL will be writt
18900 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e en into *ppDb in
18910 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 stead of a point
18920 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
18930 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e e3].** object.)^
18940 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 ^(If the databa
18950 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e se is opened (an
18960 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 d/or created) su
18970 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e ccessfully, then
18980 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 .** [SQLITE_OK]
18990 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 is returned. Ot
189a0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
189b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
189c0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b ned.)^ ^The.** [
189d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
189e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 ] or [sqlite3_er
189f0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e rmsg16()] routin
18a00 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 es can be used t
18a10 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 o obtain.** an E
18a20 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 nglish language
18a30 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 description of t
18a40 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 he error followi
18a50 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 ng a failure of
18a60 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 any.** of the sq
18a70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 lite3_open() rou
18a80 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tines..**.** ^Th
18a90 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 e default encodi
18aa0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 ng for the datab
18ab0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d ase will be UTF-
18ac0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 8 if.** sqlite3_
18ad0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
18ae0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 3_open_v2() is c
18af0 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 alled and.** UTF
18b00 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
18b10 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 e byte order if
18b20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
18b30 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
18b40 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 Whether or not a
18b50 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
18b60 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 hen it is opened
18b70 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 , resources.** a
18b80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
18b90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
18ba0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
18bb0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 should be releas
18bc0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 ed by.** passing
18bd0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
18be0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 close()] when it
18bf0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
18c00 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
18c10 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 e sqlite3_open_v
18c20 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 2() interface wo
18c30 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
18c40 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 _open().** excep
18c50 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 t that it accept
18c60 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c s two additional
18c70 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 parameters for
18c80 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
18c90 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e ol.** over the n
18ca0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
18cb0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 ection. ^(The f
18cc0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
18cd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
18ce0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 n_v2() can take
18cf0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f one of.** the fo
18d00 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 llowing three va
18d10 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 lues, optionally
18d20 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 combined with t
18d30 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f he .** [SQLITE_O
18d40 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 PEN_NOMUTEX], [S
18d50 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
18d60 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f UTEX], [SQLITE_O
18d70 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
18d80 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c ,.** and/or [SQL
18d90 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
18da0 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a CACHE] flags:)^.
18db0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 **.** <dl>.** ^(
18dc0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
18dd0 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a _READONLY]</dt>.
18de0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 ** <dd>The datab
18df0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e ase is opened in
18e00 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e read-only mode.
18e10 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 If the databas
18e20 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c e does not.** al
18e30 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 ready exist, an
18e40 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
18e50 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 d.</dd>)^.**.**
18e60 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 ^(<dt>[SQLITE_OP
18e70 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 EN_READWRITE]</d
18e80 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
18e90 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
18ea0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
18eb0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 writing if poss
18ec0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 ible, or reading
18ed0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 .** only if the
18ee0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 file is write pr
18ef0 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f otected by the o
18f00 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e perating system.
18f10 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 In either.** c
18f20 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ase the database
18f30 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 must already ex
18f40 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 ist, otherwise a
18f50 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 n error is retur
18f60 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ned.</dd>)^.**.*
18f70 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f * ^(<dt>[SQLITE_
18f80 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
18f90 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
18fa0 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c REATE]</dt>.** <
18fb0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
18fc0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
18fd0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
18fe0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 g, and is create
18ff0 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f s it if.** it do
19000 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 es not already e
19010 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 xist. This is th
19020 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 e behavior that
19030 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 is always used f
19040 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 or.** sqlite3_op
19050 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
19060 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 _open16().</dd>)
19070 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a ^.** </dl>.**.**
19080 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
19090 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
190a0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f _open_v2() is no
190b0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 t one of the.**
190c0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f combinations sho
190d0 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 wn above or one
190e0 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 of the combinati
190f0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 ons shown above
19100 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 combined.** with
19110 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
19120 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c N_NOMUTEX], [SQL
19130 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
19140 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f EX],.** [SQLITE_
19150 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
19160 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 ] and/or [SQLITE
19170 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
19180 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 E] flags,.** the
19190 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
191a0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
191b0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 ** ^If the [SQLI
191c0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
191d0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 flag is set, th
191e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
191f0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 connection.** op
19200 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 ens in the multi
19210 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
19220 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 ng mode] as long
19230 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 as the single-t
19240 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 hread.** mode ha
19250 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 s not been set a
19260 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
19270 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e r start-time. ^
19280 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
19290 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
192a0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 ] flag is set th
192b0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
192c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 connection opens
192d0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 .** in the seria
192e0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
192f0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 mode] unless si
19300 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a ngle-thread was.
19310 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
19320 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c lected at compil
19330 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d e-time or start-
19340 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 time..** ^The [S
19350 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
19360 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 DCACHE] flag cau
19370 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ses the database
19380 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 connection to b
19390 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f e.** eligible to
193a0 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 use [shared cac
193b0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 he mode], regard
193c0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
193d0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a or not shared.**
193e0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 cache is enable
193f0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
19400 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
19410 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a ache()]. ^The.*
19420 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 * [SQLITE_OPEN_P
19430 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 RIVATECACHE] fla
19440 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
19450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19460 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 to not.** parti
19470 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 cipate in [share
19480 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 d cache mode] ev
19490 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 en if it is enab
194a0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 led..**.** ^If t
194b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 he filename is "
194c0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 :memory:", then
194d0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f a private, tempo
194e0 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 rary in-memory d
194f0 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 atabase.** is cr
19500 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f eated for the co
19510 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 nnection. ^This
19520 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
19530 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 ase will vanish
19540 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 when.** the data
19550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
19560 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 is closed. Futu
19570 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
19580 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d QLite might.** m
19590 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 ake use of addit
195a0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 ional special fi
195b0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 lenames that beg
195c0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 in with the ":"
195d0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 character..** It
195e0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
195f0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 that when a data
19600 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 base filename ac
19610 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 tually does begi
19620 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 n with.** a ":"
19630 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 character you sh
19640 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 ould prefix the
19650 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 filename with a
19660 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 pathname such as
19670 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 .** "./" to avoi
19680 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a d ambiguity..**.
19690 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e ** ^If the filen
196a0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 ame is an empty
196b0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 string, then a p
196c0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
196d0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 y.** on-disk dat
196e0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 abase will be cr
196f0 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 eated. ^This pr
19700 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 ivate database w
19710 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 ill be.** automa
19720 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 tically deleted
19730 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 as soon as the d
19740 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19750 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a on is closed..**
19760 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 .** ^The fourth
19770 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
19780 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
19790 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
197a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 e.** [sqlite3_vf
197b0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
197c0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 efines the opera
197d0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 ting system inte
197e0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 rface that.** th
197f0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
19800 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 onnection should
19810 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 use. ^If the f
19820 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
19830 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 is.** a NULL poi
19840 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 nter then the de
19850 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
19860 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 fs] object is us
19870 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 ed..**.** <b>Not
19880 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 e to Windows use
19890 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 rs:</b> The enc
198a0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 oding used for t
198b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
198c0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 ment.** of sqlit
198d0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
198e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
198f0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e must be UTF-8, n
19900 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 ot whatever.** c
19910 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 odepage is curre
19920 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 ntly defined. F
19930 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e ilenames contain
19940 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 ing internationa
19950 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 l.** characters
19960 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
19970 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 d to UTF-8 prior
19980 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d to passing them
19990 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 into.** sqlite3
199a0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
199b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f e3_open_v2()..*/
199c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 .int sqlite3_ope
199d0 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 n(. const char
199e0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
199f0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
19a00 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 e (UTF-8) */. s
19a10 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 qlite3 **ppDb
19a20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
19a30 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
19a40 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
19a50 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 3_open16(. cons
19a60 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 t void *filename
19a70 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
19a80 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 filename (UTF-16
19a90 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a ) */. sqlite3 *
19aa0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f *ppDb /
19ab0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 * OUT: SQLite db
19ac0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e handle */.);.in
19ad0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 t sqlite3_open_v
19ae0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2(. const char
19af0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
19b00 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
19b10 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 e (UTF-8) */. s
19b20 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 qlite3 **ppDb,
19b30 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
19b40 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
19b50 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 */. int flags,
19b60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
19b70 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 Flags */. const
19b80 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 char *zVfs
19b90 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 /* Name of VF
19ba0 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 S module to use
19bb0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
19bc0 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 I3REF: Error Cod
19bd0 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a es And Messages.
19be0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
19bf0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 e3_errcode() int
19c00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
19c10 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 he numeric [resu
19c20 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b lt code] or.** [
19c30 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
19c40 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f code] for the mo
19c50 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 st recent failed
19c60 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 sqlite3_* API c
19c70 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 all.** associate
19c80 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 d with a [databa
19c90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
19ca0 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 If a prior API c
19cb0 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 all failed.** bu
19cc0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e t the most recen
19cd0 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 t API call succe
19ce0 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e eded, the return
19cf0 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 value from.** s
19d00 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
19d10 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 is undefined.
19d20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 ^The sqlite3_ext
19d30 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a ended_errcode().
19d40 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
19d50 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 the same except
19d60 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 that it always r
19d70 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b eturns the .** [
19d80 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
19d90 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 code] even when
19da0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
19db0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 codes are.** dis
19dc0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 abled..**.** ^Th
19dd0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 e sqlite3_errmsg
19de0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 () and sqlite3_e
19df0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e rrmsg16() return
19e00 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 English-languag
19e10 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 e.** text that d
19e20 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 escribes the err
19e30 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 or, as either UT
19e40 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 F-8 or UTF-16 re
19e50 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e spectively..** ^
19e60 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 (Memory to hold
19e70 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
19e80 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 e string is mana
19e90 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a ged internally..
19ea0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
19eb0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 on does not need
19ec0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 to worry about
19ed0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 freeing the resu
19ee0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 lt..** However,
19ef0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 the error string
19f00 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 might be overwr
19f10 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 itten or dealloc
19f20 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 ated by.** subse
19f30 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f quent calls to o
19f40 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
19f50 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e rface functions.
19f60 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 )^.**.** When th
19f70 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e serialized [th
19f80 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 reading mode] is
19f90 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 in use, it migh
19fa0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 t be the.** case
19fb0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 that a second e
19fc0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 rror occurs on a
19fd0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
19fe0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 in between.** t
19ff0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 he time of the f
1a000 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 irst error and t
1a010 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 he call to these
1a020 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
1a030 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e When that happen
1a040 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 s, the second er
1a050 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f ror will be repo
1a060 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 rted since these
1a070 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
1a080 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 lways report the
1a090 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 most recent res
1a0a0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a ult. To avoid.*
1a0b0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 * this, each thr
1a0c0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 ead can obtain e
1a0d0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 xclusive use of
1a0e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
1a0f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 nnection] D.** b
1a100 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 y invoking [sqli
1a110 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d te3_mutex_enter]
1a120 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
1a130 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 ex](D)) before b
1a140 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 eginning.** to u
1a150 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e se D and invokin
1a160 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 g [sqlite3_mutex
1a170 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 _leave]([sqlite3
1a180 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 _db_mutex](D)) a
1a190 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c fter.** all call
1a1a0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 s to the interfa
1a1b0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 ces listed here
1a1c0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a are completed..*
1a1d0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 *.** If an inter
1a1e0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 face fails with
1a1f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 SQLITE_MISUSE, t
1a200 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e hat means the in
1a210 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 terface.** was i
1a220 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 nvoked incorrect
1a230 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ly by the applic
1a240 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 ation. In that
1a250 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 case, the.** err
1a260 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 or code and mess
1a270 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e age may or may n
1a280 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e ot be set..*/.in
1a290 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 t sqlite3_errcod
1a2a0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a e(sqlite3 *db);.
1a2b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
1a2c0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c nded_errcode(sql
1a2d0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 ite3 *db);.const
1a2e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
1a2f0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b rrmsg(sqlite3*);
1a300 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
1a310 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 ite3_errmsg16(sq
1a320 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
1a330 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 CAPI3REF: SQL St
1a340 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
1a350 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 * KEYWORDS: {pre
1a360 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d pared statement}
1a370 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
1a380 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ments}.**.** An
1a390 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
1a3a0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
1a3b0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 ts a single SQL
1a3c0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 statement..** Th
1a3d0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 is object is var
1a3e0 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 iously known as
1a3f0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 a "prepared stat
1a400 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 ement" or a.** "
1a410 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 compiled SQL sta
1a420 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c tement" or simpl
1a430 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e y as a "statemen
1a440 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 t"..**.** The li
1a450 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e fe of a statemen
1a460 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f t object goes so
1a470 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 mething like thi
1a480 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
1a490 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 <li> Create the
1a4a0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
1a4b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1a4c0 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 2()] or a relate
1a4d0 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 d.** functi
1a4e0 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 on..** <li> Bind
1a4f0 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 values to [host
1a500 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 parameters] usi
1a510 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ng the sqlite3_b
1a520 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 ind_*().**
1a530 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c interfaces..** <
1a540 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 li> Run the SQL
1a550 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
1a560 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 te3_step()] one
1a570 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a or more times..*
1a580 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 * <li> Reset the
1a590 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
1a5a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1a5b0 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a )] then go back.
1a5c0 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 ** to step
1a5d0 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 2. Do this zero
1a5e0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
1a5f0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 ** <li> Destroy
1a600 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 the object using
1a610 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
1a620 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a ze()]..** </ol>.
1a630 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 **.** Refer to d
1a640 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 ocumentation on
1a650 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f individual metho
1a660 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 ds above for add
1a670 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
1a680 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 mation..*/.typed
1a690 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
1a6a0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 3_stmt sqlite3_s
1a6b0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 tmt;../*.** CAPI
1a6c0 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 3REF: Run-time L
1a6d0 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 imits.**.** ^(Th
1a6e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
1a6f0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ows the size of
1a700 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 various construc
1a710 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 ts to be limited
1a720 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 .** on a connect
1a730 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f ion by connectio
1a740 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 n basis. The fi
1a750 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
1a760 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
1a770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 e connection] wh
1a780 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 ose limit is to
1a790 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 be set or querie
1a7a0 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e d. The.** secon
1a7b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f d parameter is o
1a7c0 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 ne of the [limit
1a7d0 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 categories] tha
1a7e0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c t define a.** cl
1a7f0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 ass of construct
1a800 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d s to be size lim
1a810 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 ited. The third
1a820 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
1a830 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 e.** new limit f
1a840 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 or that construc
1a850 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e t. The function
1a860 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 returns the old
1a870 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 limit.)^.**.**
1a880 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 ^If the new limi
1a890 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 t is a negative
1a8a0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 number, the limi
1a8b0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a t is unchanged..
1a8c0 2a 2a 20 5e 28 46 6f 72 20 74 68 65 20 6c 69 6d ** ^(For the lim
1a8d0 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 it category of S
1a8e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 QLITE_LIMIT_XYZ
1a8f0 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b there is a .** [
1a900 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 limits | hard up
1a910 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 per bound].** se
1a920 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 t by a compile-t
1a930 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 ime C preprocess
1a940 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a or macro named .
1a950 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c ** [limits | SQL
1a960 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a ITE_MAX_XYZ]..**
1a970 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 (The "_LIMIT_"
1a980 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 in the name is c
1a990 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f hanged to "_MAX_
1a9a0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 ".))^.** ^Attemp
1a9b0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 ts to increase a
1a9c0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 limit above its
1a9d0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
1a9e0 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c d are.** silentl
1a9f0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 y truncated to t
1aa00 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 he hard upper li
1aa10 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 mit..**.** Run-t
1aa20 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 ime limits are i
1aa30 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
1aa40 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 in applications
1aa50 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 that manage.** b
1aa60 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e oth their own in
1aa70 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 ternal database
1aa80 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 and also databas
1aa90 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 es that are cont
1aaa0 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 rolled.** by unt
1aab0 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 rusted external
1aac0 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 sources. An exa
1aad0 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e mple application
1aae0 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 might be a.** w
1aaf0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 eb browser that
1ab00 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 has its own data
1ab10 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e bases for storin
1ab20 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a g history and.**
1ab30 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 separate databa
1ab40 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 ses controlled b
1ab50 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 y JavaScript app
1ab60 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f lications downlo
1ab70 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 aded.** off the
1ab80 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 Internet. The i
1ab90 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
1aba0 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 s can be given t
1abb0 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 he.** large, def
1abc0 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 ault limits. Da
1abd0 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 tabases managed
1abe0 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 by external sour
1abf0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 ces can.** be gi
1ac00 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 ven much smaller
1ac10 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 limits designed
1ac20 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 to prevent a de
1ac30 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a nial of service.
1ac40 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 ** attack. Deve
1ac50 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 lopers might als
1ac60 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 o want to use th
1ac70 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
1ac80 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 uthorizer()].**
1ac90 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 interface to fur
1aca0 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 ther control unt
1acb0 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 rusted SQL. The
1acc0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 size of the dat
1acd0 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 abase.** created
1ace0 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 by an untrusted
1acf0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 script can be c
1ad00 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 ontained using t
1ad10 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f he.** [max_page_
1ad20 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e count] [PRAGMA].
1ad30 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 .**.** New run-t
1ad40 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f ime limit catego
1ad50 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 ries may be adde
1ad60 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
1ad70 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ases..*/.int sql
1ad80 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 ite3_limit(sqlit
1ad90 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 e3*, int id, int
1ada0 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a newVal);../*.**
1adb0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
1adc0 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f ime Limit Catego
1add0 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ries.** KEYWORDS
1ade0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 : {limit categor
1adf0 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 y} {*limit categ
1ae00 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 ories}.**.** The
1ae10 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 se constants def
1ae20 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 ine various perf
1ae30 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a ormance limits.*
1ae40 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f * that can be lo
1ae50 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d wered at run-tim
1ae60 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 e using [sqlite3
1ae70 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 _limit()]..** Th
1ae80 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 e synopsis of th
1ae90 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 e meanings of th
1aea0 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 e various limits
1aeb0 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e is shown below.
1aec0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 .** Additional i
1aed0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 nformation is av
1aee0 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 ailable at [limi
1aef0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 ts | Limits in S
1af00 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 QLite]..**.** <d
1af10 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 l>.** ^(<dt>SQLI
1af20 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c TE_LIMIT_LENGTH<
1af30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1af40 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 maximum size of
1af50 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c any string or BL
1af60 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e OB or table row.
1af70 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c <dd>)^.**.** ^(<
1af80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1af90 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a SQL_LENGTH</dt>.
1afa0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1afb0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 um length of an
1afc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 SQL statement, i
1afd0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a n bytes.</dd>)^.
1afe0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 **.** ^(<dt>SQLI
1aff0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c TE_LIMIT_COLUMN<
1b000 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1b010 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
1b020 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 f columns in a t
1b030 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 able definition
1b040 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 or in the.** res
1b050 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
1b060 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 LECT] or the max
1b070 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
1b080 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 olumns in an ind
1b090 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f ex.** or in an O
1b0a0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 RDER BY or GROUP
1b0b0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e BY clause.</dd>
1b0c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 )^.**.** ^(<dt>S
1b0d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 QLITE_LIMIT_EXPR
1b0e0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c _DEPTH</dt>.** <
1b0f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 dd>The maximum d
1b100 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 epth of the pars
1b110 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 e tree on any ex
1b120 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e pression.</dd>)^
1b130 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c .**.** ^(<dt>SQL
1b140 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
1b150 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a ND_SELECT</dt>.*
1b160 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1b170 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d m number of term
1b180 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 s in a compound
1b190 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
1b1a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
1b1b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
1b1c0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a T_VDBE_OP</dt>.*
1b1d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1b1e0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 m number of inst
1b1f0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 ructions in a vi
1b200 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 rtual machine pr
1b210 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f ogram.** used to
1b220 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 implement an SQ
1b230 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 L statement.</dd
1b240 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
1b250 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
1b260 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a CTION_ARG</dt>.*
1b270 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1b280 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 m number of argu
1b290 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 ments on a funct
1b2a0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ion.</dd>)^.**.*
1b2b0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c * ^(<dt>SQLITE_L
1b2c0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 IMIT_ATTACHED</d
1b2d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1b2e0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
1b2f0 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 [ATTACH | attach
1b300 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 3c 2f ed databases].</
1b310 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 3c 64 74 3e 53 dd>.**.** ^<dt>S
1b320 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 QLITE_LIMIT_LIKE
1b330 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c _PATTERN_LENGTH<
1b340 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1b350 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
1b360 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 f the pattern ar
1b370 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c gument to the [L
1b380 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 IKE] or.** [GLOB
1b390 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 ] operators.</dd
1b3a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
1b3b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
1b3c0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 IABLE_NUMBER</dt
1b3d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
1b3e0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 imum number of v
1b3f0 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 ariables in an S
1b400 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 QL statement tha
1b410 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e t can.** be boun
1b420 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 d.</dd>)^.**.**
1b430 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
1b440 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 IT_TRIGGER_DEPTH
1b450 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1b460 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f maximum depth o
1b470 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 f recursion for
1b480 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e triggers.</dd>)^
1b490 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
1b4a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
1b4b0 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 T_LENGTH
1b4c0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 0.#d
1b4d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
1b4e0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 IT_SQL_LENGTH
1b4f0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 1.#
1b500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
1b510 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 MIT_COLUMN
1b520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 2.
1b530 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1b540 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 IMIT_EXPR_DEPTH
1b550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 3
1b560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b570 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 LIMIT_COMPOUND_S
1b580 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 ELECT
1b590 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
1b5a0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 _LIMIT_VDBE_OP
1b5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1b5c0 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 5.#define SQLIT
1b5d0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
1b5e0 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 _ARG
1b5f0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
1b600 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
1b610 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 D
1b620 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 7.#define SQL
1b630 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
1b640 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 ATTERN_LENGTH
1b650 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 8.#define SQ
1b660 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
1b670 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 BLE_NUMBER
1b680 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 9.#define S
1b690 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 QLITE_LIMIT_TRIG
1b6a0 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 GER_DEPTH
1b6b0 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 10../*.** C
1b6c0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 API3REF: Compili
1b6d0 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d ng An SQL Statem
1b6e0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ent.** KEYWORDS:
1b6f0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 {SQL statement
1b700 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 compiler}.**.**
1b710 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 To execute an SQ
1b720 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 L query, it must
1b730 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c first be compil
1b740 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 ed into a byte-c
1b750 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 ode.** program u
1b760 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 sing one of thes
1b770 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a e routines..**.*
1b780 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
1b790 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 ment, "db", is a
1b7a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1b7b0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 ction] obtained
1b7c0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 from a.** prior
1b7d0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
1b7e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
1b7f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
1b800 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b en_v2()] or.** [
1b810 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1b820 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 ]. The database
1b830 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 connection must
1b840 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 not have been c
1b850 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 losed..**.** The
1b860 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
1b870 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 , "zSql", is the
1b880 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
1b890 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 compiled, encod
1b8a0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 ed.** as either
1b8b0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e UTF-8 or UTF-16.
1b8c0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 The sqlite3_pr
1b8d0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 epare() and sqli
1b8e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1b8f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 .** interfaces u
1b900 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 se UTF-8, and sq
1b910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
1b920 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
1b930 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 epare16_v2().**
1b940 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a use UTF-16..**.*
1b950 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 * ^If the nByte
1b960 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 argument is less
1b970 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e than zero, then
1b980 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 zSql is read up
1b990 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 to the.** first
1b9a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
1b9b0 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e . ^If nByte is n
1b9c0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
1b9d0 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 n it is the maxi
1b9e0 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 mum.** number of
1b9f0 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f bytes read fro
1ba00 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e m zSql. ^When n
1ba10 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 Byte is non-nega
1ba20 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 tive, the.** zSq
1ba30 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 l string ends at
1ba40 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 either the firs
1ba50 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 t '\000' or '\u0
1ba60 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 000' character o
1ba70 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 r.** the nByte-t
1ba80 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 h byte, whicheve
1ba90 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 r comes first. I
1baa0 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f f the caller kno
1bab0 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 ws.** that the s
1bac0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 upplied string i
1bad0 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 s nul-terminated
1bae0 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 , then there is
1baf0 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f a small.** perfo
1bb00 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 rmance advantage
1bb10 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 to be gained by
1bb20 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 passing an nByt
1bb30 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
1bb40 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 .** is equal to
1bb50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
1bb60 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 tes in the input
1bb70 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 string <i>inclu
1bb80 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 ding</i>.** the
1bb90 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 nul-terminator b
1bba0 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ytes..**.** ^If
1bbb0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 pzTail is not NU
1bbc0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 LL then *pzTail
1bbd0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
1bbe0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 to the first by
1bbf0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 te.** past the e
1bc00 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 nd of the first
1bc10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
1bc20 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f zSql. These ro
1bc30 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 utines only.** c
1bc40 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 ompile the first
1bc50 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
1bc60 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 ql, so *pzTail i
1bc70 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
1bc80 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 to.** what remai
1bc90 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a ns uncompiled..*
1bca0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 *.** ^*ppStmt is
1bcb0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
1bcc0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 o a compiled [pr
1bcd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1bce0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a ] that can be.**
1bcf0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 executed using
1bd00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1bd10 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 . ^If there is
1bd20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d an error, *ppStm
1bd30 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e t is set.** to N
1bd40 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e ULL. ^If the in
1bd50 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
1bd60 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 s no SQL (if the
1bd70 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 input is an emp
1bd80 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 ty.** string or
1bd90 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 a comment) then
1bda0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 *ppStmt is set t
1bdb0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 o NULL..** The c
1bdc0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 alling procedure
1bdd0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
1bde0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 for deleting the
1bdf0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c compiled.** SQL
1be00 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
1be10 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
1be20 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 ze()] after it h
1be30 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1be40 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d it..** ppStmt m
1be50 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a ay not be NULL..
1be60 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 **.** ^On succes
1be70 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 s, the sqlite3_p
1be80 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 repare() family
1be90 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 of routines retu
1bea0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a rn [SQLITE_OK];.
1beb0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 ** otherwise an
1bec0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
1bed0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
1bee0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
1bef0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c are_v2() and sql
1bf00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1bf10 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 2() interfaces a
1bf20 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 re.** recommende
1bf30 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 d for all new pr
1bf40 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 ograms. The two
1bf50 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 older interfaces
1bf60 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a are retained.**
1bf70 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
1bf80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 ompatibility, bu
1bf90 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 t their use is d
1bfa0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e iscouraged..** ^
1bfb0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 In the "v2" inte
1bfc0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 rfaces, the prep
1bfd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
1bfe0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e * that is return
1bff0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 ed (the [sqlite3
1c000 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 _stmt] object) c
1c010 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f ontains a copy o
1c020 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 f the.** origina
1c030 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 l SQL text. This
1c040 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c causes the [sql
1c050 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 ite3_step()] int
1c060 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 erface to.** beh
1c070 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 ave differently
1c080 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a in three ways:.*
1c090 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
1c0a0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 >.** ^If the dat
1c0b0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 abase schema cha
1c0c0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 nges, instead of
1c0d0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 returning [SQLI
1c0e0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 TE_SCHEMA] as it
1c0f0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 .** always used
1c100 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f to do, [sqlite3_
1c110 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 step()] will aut
1c120 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d omatically recom
1c130 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 pile the SQL.**
1c140 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 statement and tr
1c150 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 y to run it agai
1c160 6e 2e 20 20 5e 49 66 20 74 68 65 20 73 63 68 65 n. ^If the sche
1c170 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 ma has changed i
1c180 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 n.** a way that
1c190 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d makes the statem
1c1a0 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 ent no longer va
1c1b0 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 lid, [sqlite3_st
1c1c0 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c ep()] will still
1c1d0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
1c1e0 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 TE_SCHEMA]. But
1c1f0 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 unlike the lega
1c200 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 cy behavior, [SQ
1c210 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a LITE_SCHEMA] is.
1c220 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 ** now a fatal e
1c230 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b rror. Calling [
1c240 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1c250 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c v2()] again will
1c260 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a not make the.**
1c270 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 error go away.
1c280 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 Note: use [sqli
1c290 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f te3_errmsg()] to
1c2a0 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a find the text.*
1c2b0 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 * of the parsing
1c2c0 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 error that resu
1c2d0 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 lts in an [SQLIT
1c2e0 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e E_SCHEMA] return
1c2f0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a ..** </li>.**.**
1c300 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 <li>.** ^When a
1c310 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 n error occurs,
1c320 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1c330 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 will return one
1c340 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 of the detailed
1c350 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 .** [error codes
1c360 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 ] or [extended e
1c370 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 rror codes]. ^T
1c380 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
1c390 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b or was that.** [
1c3a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1c3b0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 would only retur
1c3c0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c n a generic [SQL
1c3d0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c ITE_ERROR] resul
1c3e0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 t code.** and th
1c3f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f e application wo
1c400 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 uld have to make
1c410 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 a second call t
1c420 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
1c430 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 ()].** in order
1c440 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 to find the unde
1c450 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 rlying cause of
1c460 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 the problem. Wit
1c470 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 h the "v2" prepa
1c480 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 re.** interfaces
1c490 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 , the underlying
1c4a0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 reason for the
1c4b0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
1c4c0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a d immediately..*
1c4d0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c * </li>.**.** <l
1c4e0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 i>.** ^If the va
1c4f0 6c 75 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65 lue of a [parame
1c500 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d ter | host param
1c510 65 74 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45 eter] in the WHE
1c520 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a RE clause might.
1c530 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 71 75 ** change the qu
1c540 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 ery plan for a s
1c550 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 tatement, then t
1c560 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79 he statement may
1c570 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 be.** automatic
1c580 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20 ally recompiled
1c590 28 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 (as if there had
1c5a0 20 62 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63 been a schema c
1c5b0 68 61 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69 hange) on the fi
1c5c0 72 73 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 rst .** [sqlite3
1c5d0 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f _step()] call fo
1c5e0 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e llowing any chan
1c5f0 67 65 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 ge to the .** [s
1c600 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
1c610 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 | bindings] of
1c620 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e the [parameter].
1c630 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f .** </li>.** </
1c640 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ol>.*/.int sqlit
1c650 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 e3_prepare(. sq
1c660 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
1c670 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
1c680 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
1c690 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 nst char *zSql,
1c6a0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
1c6b0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e tement, UTF-8 en
1c6c0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
1c6d0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
1c6e0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
1c6f0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
1c700 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
1c710 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
1c720 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
1c730 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
1c740 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 const char **p
1c750 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
1c760 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
1c770 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
1c780 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 Sql */.);.int sq
1c790 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1c7a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
1c7b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
1c7c0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
1c7d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1c7e0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
1c7f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
1c800 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 F-8 encoded */.
1c810 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
1c820 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
1c830 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
1c840 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
1c850 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
1c860 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
1c870 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
1c880 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
1c890 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 ar **pzTail
1c8a0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
1c8b0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
1c8c0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
1c8d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
1c8e0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 are16(. sqlite3
1c8f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
1c900 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
1c910 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
1c920 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
1c930 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
1c940 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
1c950 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
1c960 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
1c970 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
1c980 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
1c990 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
1c9a0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
1c9b0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
1c9c0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
1c9d0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
1c9e0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
1c9f0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
1ca00 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
1ca10 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
1ca20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 3_prepare16_v2(.
1ca30 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1ca40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
1ca50 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
1ca60 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
1ca70 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
1ca80 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
1ca90 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
1caa0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
1cab0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
1cac0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
1cad0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
1cae0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
1caf0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
1cb00 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
1cb10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
1cb20 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
1cb30 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
1cb40 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
1cb50 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a of zSql */.);..
1cb60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1cb70 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 Retrieving State
1cb80 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e ment SQL.**.** ^
1cb90 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
1cba0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 an be used to re
1cbb0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 trieve a saved c
1cbc0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 opy of the origi
1cbd0 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 nal.** SQL text
1cbe0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 used to create a
1cbf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1cc00 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 ment] if that st
1cc10 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 atement was.** c
1cc20 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 ompiled using ei
1cc30 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
1cc40 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b epare_v2()] or [
1cc50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1cc60 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 6_v2()]..*/.cons
1cc70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
1cc80 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 sql(sqlite3_stmt
1cc90 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
1cca0 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d CAPI3REF: Dynam
1ccb0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c ically Typed Val
1ccc0 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 ue Object.** KEY
1ccd0 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 WORDS: {protecte
1cce0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d d sqlite3_value}
1ccf0 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 {unprotected sq
1cd00 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a lite3_value}.**.
1cd10 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 ** SQLite uses t
1cd20 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
1cd30 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 object to repre
1cd40 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a sent all values.
1cd50 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 ** that can be s
1cd60 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 tored in a datab
1cd70 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 ase table. SQLit
1cd80 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 e uses dynamic t
1cd90 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 yping.** for the
1cda0 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 values it store
1cdb0 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 s. ^Values stor
1cdc0 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 ed in sqlite3_va
1cdd0 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 lue objects.** c
1cde0 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 an be integers,
1cdf0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
1ce00 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 alues, strings,
1ce10 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a BLOBs, or NULL..
1ce20 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 **.** An sqlite3
1ce30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 _value object ma
1ce40 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f y be either "pro
1ce50 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 tected" or "unpr
1ce60 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d otected"..** Som
1ce70 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 e interfaces req
1ce80 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 uire a protected
1ce90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 sqlite3_value.
1cea0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 Other interface
1ceb0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 s.** will accept
1cec0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 either a protec
1ced0 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ted or an unprot
1cee0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
1cef0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e lue..** Every in
1cf00 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 terface that acc
1cf10 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c epts sqlite3_val
1cf20 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 ue arguments spe
1cf30 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 cifies.** whethe
1cf40 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 r or not it requ
1cf50 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 ires a protected
1cf60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
1cf70 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 **.** The terms
1cf80 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 "protected" and
1cf90 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 "unprotected" re
1cfa0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f fer to whether o
1cfb0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 r not.** a mutex
1cfc0 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 is held. A int
1cfd0 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 ernal mutex is h
1cfe0 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 eld for a protec
1cff0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
1d000 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 alue object but
1d010 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 no mutex is held
1d020 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 for an unprotec
1d030 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
1d040 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 alue object. If
1d050 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
1d060 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 led to be single
1d070 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 -threaded.** (wi
1d080 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 th [SQLITE_THREA
1d090 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 DSAFE=0] and wit
1d0a0 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 h [sqlite3_threa
1d0b0 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 dsafe()] returni
1d0c0 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 ng 0).** or if S
1d0d0 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 QLite is run in
1d0e0 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d one of reduced m
1d0f0 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b utex modes .** [
1d100 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
1d110 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b NGLETHREAD] or [
1d120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
1d130 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 LTITHREAD].** th
1d140 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 en there is no d
1d150 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 istinction betwe
1d160 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
1d170 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
1d180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1d190 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 jects and they c
1d1a0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 an be used inter
1d1b0 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 changeably. How
1d1c0 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 ever,.** for max
1d1d0 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 imum code portab
1d1e0 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f ility it is reco
1d1f0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
1d200 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 lications.** sti
1d210 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 ll make the dist
1d220 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 inction between
1d230 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
1d240 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
1d250 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
1d260 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 ue objects even
1d270 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c when not strictl
1d280 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a y required..**.*
1d290 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
1d2a0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 alue objects tha
1d2b0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 t are passed as
1d2c0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 parameters into
1d2d0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
1d2e0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 ation of [applic
1d2f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
1d300 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 L functions] are
1d310 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e protected..** ^
1d320 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
1d330 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
1d340 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
1d350 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
1d360 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e is unprotected.
1d370 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 .** Unprotected
1d380 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1d390 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 jects may only b
1d3a0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b e used with.** [
1d3b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
1d3c0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
1d3d0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
1d3e0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 )]..** The [sqli
1d3f0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c te3_value_blob |
1d400 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
1d410 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 ype()] family of
1d420 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 .** interfaces r
1d430 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 equire protected
1d440 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1d450 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 bjects..*/.typed
1d460 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 ef struct Mem sq
1d470 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
1d480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
1d490 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 L Function Conte
1d4a0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 xt Object.**.**
1d4b0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 The context in w
1d4c0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 hich an SQL func
1d4d0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 tion executes is
1d4e0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a stored in an.**
1d4f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
1d500 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 object. ^A poi
1d510 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 nter to an sqlit
1d520 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
1d530 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 t.** is always f
1d540 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
1d550 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 o [application-d
1d560 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
1d570 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 ions]..** The ap
1d580 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
1d590 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 d SQL function i
1d5a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
1d5b0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 ll pass this.**
1d5c0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 pointer through
1d5d0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 into calls to [s
1d5e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
1d5f0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 t | sqlite3_resu
1d600 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 lt()],.** [sqlit
1d610 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
1d620 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 text()], [sqlite
1d630 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 3_user_data()],.
1d640 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
1d650 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d ext_db_handle()]
1d660 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 , [sqlite3_get_a
1d670 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e uxdata()],.** an
1d680 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 d/or [sqlite3_se
1d690 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f t_auxdata()]..*/
1d6a0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
1d6b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
1d6c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b sqlite3_context;
1d6d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1d6e0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 : Binding Values
1d6f0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
1d700 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f tements.** KEYWO
1d710 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d RDS: {host param
1d720 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 eter} {host para
1d730 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 meters} {host pa
1d740 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a rameter name}.**
1d750 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
1d760 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 parameter} {SQL
1d770 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 parameters} {par
1d780 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a ameter binding}.
1d790 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 **.** ^(In the S
1d7a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
1d7b0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 t input to [sqli
1d7c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1d7d0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e ] and its varian
1d7e0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 ts,.** literals
1d7f0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 may be replaced
1d800 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d by a [parameter]
1d810 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e that matches on
1d820 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a e of following.*
1d830 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a * templates:.**.
1d840 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
1d850 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e ?.** <li> ?NNN
1d860 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a .** <li> :VVV.*
1d870 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 * <li> @VVV.**
1d880 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f <li> $VVV.** </
1d890 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 ul>.**.** In the
1d8a0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 templates above
1d8b0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 , NNN represents
1d8c0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 an integer lite
1d8d0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 ral,.** and VVV
1d8e0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c represents an al
1d8f0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 phanumeric ident
1d900 69 66 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 ifer.)^ ^The va
1d910 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a lues of these.**
1d920 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 parameters (als
1d930 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 o called "host p
1d940 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 arameter names"
1d950 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 or "SQL paramete
1d960 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 rs").** can be s
1d970 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c et using the sql
1d980 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
1d990 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 utines defined h
1d9a0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ere..**.** ^The
1d9b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
1d9c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 o the sqlite3_bi
1d9d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
1d9e0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 is always.** a p
1d9f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ointer to the [s
1da00 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
1da10 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f ect returned fro
1da20 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 m.** [sqlite3_pr
1da30 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 epare_v2()] or i
1da40 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a ts variants..**.
1da50 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 ** ^The second a
1da60 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 rgument is the i
1da70 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 ndex of the SQL
1da80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 parameter to be
1da90 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 set..** ^The lef
1daa0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 tmost SQL parame
1dab0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 ter has an index
1dac0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 of 1. ^When th
1dad0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 e same named.**
1dae0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 SQL parameter is
1daf0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 used more than
1db00 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 once, second and
1db10 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f subsequent.** o
1db20 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 ccurrences have
1db30 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 the same index a
1db40 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 s the first occu
1db50 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 rrence..** ^The
1db60 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 index for named
1db70 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 parameters can b
1db80 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e e looked up usin
1db90 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
1dba0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1dbb0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 _index()] API if
1dbc0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 desired. ^The
1dbd0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e index.** for "?N
1dbe0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 NN" parameters i
1dbf0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e s the value of N
1dc00 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 NN..** ^The NNN
1dc10 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 value must be be
1dc20 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 tween 1 and the
1dc30 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
1dc40 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b ].** parameter [
1dc50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
1dc60 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 IABLE_NUMBER] (d
1dc70 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 efault value: 99
1dc80 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 9)..**.** ^The t
1dc90 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
1dca0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 the value to bi
1dcb0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 nd to the parame
1dcc0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 ter..**.** ^(In
1dcd0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 those routines t
1dce0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 hat have a fourt
1dcf0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 h argument, its
1dd00 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
1dd10 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
1dd20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 in the parameter
1dd30 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 . To be clear:
1dd40 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 the value is the
1dd50 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 .** number of <u
1dd60 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 >bytes</u> in th
1dd70 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 e value, not the
1dd80 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
1dd90 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 cters.)^.** ^If
1dda0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
1ddb0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 eter is negative
1ddc0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 , the length of
1ddd0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a the string is.**
1dde0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
1ddf0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 ytes up to the f
1de00 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
1de10 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ator..**.** ^The
1de20 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 fifth argument
1de30 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
1de40 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f blob(), sqlite3_
1de50 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 bind_text(), and
1de60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 .** sqlite3_bind
1de70 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 _text16() is a d
1de80 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 estructor used t
1de90 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 o dispose of the
1dea0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 BLOB or.** stri
1deb0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 ng after SQLite
1dec0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
1ded0 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20 66 69 h it. ^If the fi
1dee0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a fth argument is.
1def0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 ** the special v
1df00 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 alue [SQLITE_STA
1df10 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 TIC], then SQLit
1df20 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
1df30 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f he.** informatio
1df40 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 n is in static,
1df50 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 unmanaged space
1df60 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 and does not nee
1df70 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a d to be freed..*
1df80 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
1df90 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
1dfa0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
1dfb0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
1dfc0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
1dfd0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
1dfe0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
1dff0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
1e000 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
1e010 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
1e020 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
1e030 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1e040 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 _bind_zeroblob()
1e050 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 routine binds a
1e060 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 BLOB of length
1e070 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c N that.** is fil
1e080 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e led with zeroes.
1e090 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 ^A zeroblob us
1e0a0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e es a fixed amoun
1e0b0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 t of memory.** (
1e0c0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 just an integer
1e0d0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 to hold its size
1e0e0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 ) while it is be
1e0f0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a ing processed..*
1e100 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 * Zeroblobs are
1e110 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 intended to serv
1e120 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 e as placeholder
1e130 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 s for BLOBs whos
1e140 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 e.** content is
1e150 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 later written us
1e160 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
1e170 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 blob_open | incr
1e180 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f emental BLOB I/O
1e190 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e ] routines..** ^
1e1a0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 A negative value
1e1b0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f for the zeroblo
1e1c0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a b results in a z
1e1d0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e ero-length BLOB.
1e1e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f .**.** ^If any o
1e1f0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 f the sqlite3_bi
1e200 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
1e210 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 are called with
1e220 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
1e230 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 * for the [prepa
1e240 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
1e250 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 r with a prepare
1e260 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 d statement for
1e270 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 which.** [sqlite
1e280 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 3_step()] has be
1e290 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 en called more r
1e2a0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 ecently than [sq
1e2b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a lite3_reset()],.
1e2c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c ** then the call
1e2d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
1e2e0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 LITE_MISUSE]. I
1e2f0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 f any sqlite3_bi
1e300 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 nd_().** routine
1e310 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 is passed a [pr
1e320 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1e330 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 ] that has been
1e340 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a finalized, the.*
1e350 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 * result is unde
1e360 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
1e370 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a ly harmful..**.*
1e380 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 * ^Bindings are
1e390 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 not cleared by t
1e3a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
1e3b0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a t()] routine..**
1e3c0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 ^Unbound parame
1e3d0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 ters are interpr
1e3e0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a eted as NULL..**
1e3f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1e400 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 _bind_* routines
1e410 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1e420 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
1e430 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 r an.** [error c
1e440 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 ode] if anything
1e450 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 goes wrong..**
1e460 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 ^[SQLITE_RANGE]
1e470 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
1e480 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
1e490 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
1e4a0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 range. ^[SQLITE
1e4b0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 _NOMEM] is retur
1e4c0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 ned if malloc()
1e4d0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 fails..**.** See
1e4e0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
1e4f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
1e500 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c ount()],.** [sql
1e510 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1e520 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 ter_name()], and
1e530 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1e540 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
1e550 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
1e560 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 3_bind_blob(sqli
1e570 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
1e580 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
1e590 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 n, void(*)(void
1e5a0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
1e5b0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c _bind_double(sql
1e5c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
1e5d0 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 double);.int sq
1e5e0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 lite3_bind_int(s
1e5f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1e600 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c t, int);.int sql
1e610 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 ite3_bind_int64(
1e620 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1e630 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 nt, sqlite3_int6
1e640 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 4);.int sqlite3_
1e650 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 bind_null(sqlite
1e660 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 3_stmt*, int);.i
1e670 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1e680 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
1e690 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 t*, int, const c
1e6a0 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 har*, int n, voi
1e6b0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
1e6c0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
1e6d0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
1e6e0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
1e6f0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
1e700 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
1e710 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
1e720 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
1e730 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
1e740 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
1e750 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1e760 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
1e770 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
1e780 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
1e790 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
1e7a0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a SQL Parameters.*
1e7b0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
1e7c0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ne can be used t
1e7d0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 o find the numbe
1e7e0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 r of [SQL parame
1e7f0 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 ters].** in a [p
1e800 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1e810 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 t]. SQL paramet
1e820 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f ers are tokens o
1e830 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f f the.** form "?
1e840 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 ", "?NNN", ":AAA
1e850 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 ", "$AAA", or "@
1e860 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 AAA" that serve
1e870 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 as.** placeholde
1e880 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 rs for values th
1e890 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f at are [sqlite3_
1e8a0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e bind_blob | boun
1e8b0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 d].** to the par
1e8c0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 ameters at a lat
1e8d0 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e er time..**.** ^
1e8e0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 (This routine ac
1e8f0 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 tually returns t
1e900 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
1e910 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f largest (rightmo
1e920 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 st).** parameter
1e930 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 . For all forms
1e940 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 except ?NNN, thi
1e950 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e s will correspon
1e960 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 d to the.** numb
1e970 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 er of unique par
1e980 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 ameters. If par
1e990 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f ameters of the ?
1e9a0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 NNN form are use
1e9b0 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 d,.** there may
1e9c0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c be gaps in the l
1e9d0 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 ist.)^.**.** See
1e9e0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
1e9f0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
1ea00 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
1ea10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1ea20 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 meter_name()], a
1ea30 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
1ea40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
1ea50 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 dex()]..*/.int s
1ea60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1ea70 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 meter_count(sqli
1ea80 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
1ea90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d ** CAPI3REF: Nam
1eaa0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 e Of A Host Para
1eab0 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 meter.**.** ^The
1eac0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
1ead0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e rameter_name(P,N
1eae0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
1eaf0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 rns.** the name
1eb00 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c of the N-th [SQL
1eb10 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 parameter] in t
1eb20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
1eb30 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 tement] P..** ^(
1eb40 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f SQL parameters o
1eb50 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e f the form "?NNN
1eb60 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
1eb70 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
1eb80 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 ** have a name w
1eb90 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 hich is the stri
1eba0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 ng "?NNN" or ":A
1ebb0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
1ebc0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 "$AAA".** respe
1ebd0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f ctively..** In o
1ebe0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
1ebf0 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 initial ":" or "
1ec00 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 $" or "@" or "?"
1ec10 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 .** is included
1ec20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e as part of the n
1ec30 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d ame.)^.** ^Param
1ec40 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
1ec50 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 m "?" without a
1ec60 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 following intege
1ec70 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a r have no name.*
1ec80 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 * and are referr
1ec90 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 ed to as "namele
1eca0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 ss" or "anonymou
1ecb0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a s parameters"..*
1ecc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
1ecd0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 host parameter h
1ece0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
1ecf0 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e , not 0..**.** ^
1ed00 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 If the value N i
1ed10 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f s out of range o
1ed20 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 r if the N-th pa
1ed30 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 rameter is.** na
1ed40 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c meless, then NUL
1ed50 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 L is returned.
1ed60 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
1ed70 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 ring is.** alway
1ed80 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 s in UTF-8 encod
1ed90 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
1eda0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 named parameter
1edb0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c was.** originall
1edc0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 y specified as U
1edd0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 TF-16 in [sqlite
1ede0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 3_prepare16()] o
1edf0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
1ee00 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
1ee10 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
1ee20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1ee30 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
1ee40 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
1ee50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
1ee60 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b unt()], and.** [
1ee70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1ee80 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
1ee90 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
1eea0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1eeb0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 ameter_name(sqli
1eec0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
1eed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1eee0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 : Index Of A Par
1eef0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 ameter With A Gi
1ef00 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e ven Name.**.** ^
1ef10 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 Return the index
1ef20 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d of an SQL param
1ef30 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e eter given its n
1ef40 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e ame. ^The.** in
1ef50 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e dex value return
1ef60 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 ed is suitable f
1ef70 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 or use as the se
1ef80 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 cond.** paramete
1ef90 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 r to [sqlite3_bi
1efa0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
1efb0 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 bind()]. ^A zer
1efc0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 o.** is returned
1efd0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 if no matching
1efe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 parameter is fou
1eff0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 nd. ^The parame
1f000 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 ter.** name must
1f010 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 be given in UTF
1f020 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f -8 even if the o
1f030 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e riginal statemen
1f040 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 t.** was prepare
1f050 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 d from UTF-16 te
1f060 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 xt using [sqlite
1f070 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
1f080 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
1f090 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
1f0a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
1f0b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
1f0c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1f0d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
1f0e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
1f0f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
1f100 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
1f110 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1f120 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 er_index(sqlite3
1f130 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 _stmt*, const ch
1f140 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a ar *zName);../*.
1f150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
1f160 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 et All Bindings
1f170 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 On A Prepared St
1f180 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 atement.**.** ^C
1f190 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
1f1a0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
1f1b0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
1f1c0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 ()] does not res
1f1d0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 et.** the [sqlit
1f1e0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
1f1f0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 indings] on a [p
1f200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1f210 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 t]..** ^Use this
1f220 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 routine to rese
1f230 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d t all host param
1f240 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a eters to NULL..*
1f250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
1f260 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c ear_bindings(sql
1f270 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
1f280 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
1f290 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 mber Of Columns
1f2a0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a In A Result Set.
1f2b0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 **.** ^Return th
1f2c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
1f2d0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
1f2e0 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 t set returned b
1f2f0 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 y the.** [prepar
1f300 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e ed statement]. ^
1f310 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
1f320 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 urns 0 if pStmt
1f330 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 is an SQL.** sta
1f340 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 tement that does
1f350 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 not return data
1f360 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e (for example an
1f370 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a 69 [UPDATE])..*/.i
1f380 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
1f390 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f n_count(sqlite3_
1f3a0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
1f3b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
1f3c0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 olumn Names In A
1f3d0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a Result Set.**.*
1f3e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
1f3f0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d s return the nam
1f400 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 e assigned to a
1f410 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d particular colum
1f420 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 n.** in the resu
1f430 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c lt set of a [SEL
1f440 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
1f450 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
1f460 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 lumn_name().** i
1f470 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
1f480 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1f490 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1f4a0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
1f4b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
1f4c0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 mn_name16() retu
1f4d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1f4e0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
1f4f0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
1f500 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ing. ^The first
1f510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
1f520 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
1f530 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 ement].** that i
1f540 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 mplements the [S
1f550 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
1f560 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
1f570 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
1f580 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e * column number.
1f590 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 ^The leftmost
1f5a0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 column is number
1f5b0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 0..**.** ^The r
1f5c0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 eturned string p
1f5d0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 ointer is valid
1f5e0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 until either the
1f5f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1f600 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 ment].** is dest
1f610 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
1f620 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
1f630 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 until the next
1f640 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 call to.** sqlit
1f650 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
1f660 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
1f670 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 mn_name16() on t
1f680 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a he same column..
1f690 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 **.** ^If sqlite
1f6a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 3_malloc() fails
1f6b0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 during the proc
1f6c0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 essing of either
1f6d0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 routine.** (for
1f6e0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 example during
1f6f0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f a conversion fro
1f700 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 m UTF-8 to UTF-1
1f710 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 6) then a.** NUL
1f720 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
1f730 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 urned..**.** ^Th
1f740 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 e name of a resu
1f750 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 lt column is the
1f760 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 value of the "A
1f770 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a S" clause for.**
1f780 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 that column, if
1f790 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 there is an AS
1f7a0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 clause. If ther
1f7b0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 e is no AS claus
1f7c0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 e.** then the na
1f7d0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e me of the column
1f7e0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 is unspecified
1f7f0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 and may change f
1f800 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 rom.** one relea
1f810 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 se of SQLite to
1f820 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e the next..*/.con
1f830 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
1f840 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c _column_name(sql
1f850 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
1f860 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a N);.const void *
1f870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
1f880 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
1f890 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a mt*, int N);../*
1f8a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f .** CAPI3REF: So
1f8b0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 urce Of Data In
1f8c0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a A Query Result.*
1f8d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
1f8e0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d ines provide a m
1f8f0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e eans to determin
1f900 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 e the database,
1f910 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 table, and.** ta
1f920 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
1f930 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 is the origin of
1f940 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
1f950 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a sult column in.*
1f960 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 * [SELECT] state
1f970 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 ment..** ^The na
1f980 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
1f990 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 se or table or c
1f9a0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 olumn can be ret
1f9b0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 urned as.** eith
1f9c0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 er a UTF-8 or UT
1f9d0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 F-16 string. ^T
1f9e0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f he _database_ ro
1f9f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a utines return.**
1fa00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
1fa10 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 me, the _table_
1fa20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1fa30 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 the table name,
1fa40 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 and.** the origi
1fa50 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 n_ routines retu
1fa60 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 rn the column na
1fa70 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 me..** ^The retu
1fa80 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 rned string is v
1fa90 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b alid until the [
1faa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1fab0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 nt] is destroyed
1fac0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
1fad0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
1fae0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 r until the same
1faf0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
1fb00 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 requested.** aga
1fb10 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e in in a differen
1fb20 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a t encoding..**.*
1fb30 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 * ^The names ret
1fb40 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 urned are the or
1fb50 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 iginal un-aliase
1fb60 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a d names of the.*
1fb70 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c * database, tabl
1fb80 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a e, and column..*
1fb90 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
1fba0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 argument to thes
1fbb0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 e interfaces is
1fbc0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
1fbd0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 ement]..** ^Thes
1fbe0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
1fbf0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 rn information a
1fc00 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 bout the Nth res
1fc10 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 ult column retur
1fc20 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 ned by.** the st
1fc30 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e atement, where N
1fc40 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 is the second f
1fc50 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
1fc60 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d ..** ^The left-m
1fc70 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f ost column is co
1fc80 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 lumn 0 for these
1fc90 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
1fca0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c ^If the Nth col
1fcb0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 umn returned by
1fcc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
1fcd0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f an expression o
1fce0 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e r.** subquery an
1fcf0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d d is not a colum
1fd00 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c n value, then al
1fd10 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 l of these funct
1fd20 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e ions return.** N
1fd30 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 ULL. ^These rou
1fd40 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 tine might also
1fd50 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 return NULL if a
1fd60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1fd70 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 on error.** occu
1fd80 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c rs. ^Otherwise,
1fd90 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 they return the
1fda0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 name of the att
1fdb0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 ached database,
1fdc0 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c table,.** or col
1fdd0 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 umn that query r
1fde0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 esult column was
1fdf0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e extracted from.
1fe00 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 .**.** ^As with
1fe10 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 all other SQLite
1fe20 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f APIs, those who
1fe30 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 se names end wit
1fe40 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a h "16" return.**
1fe50 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
1fe60 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 strings and the
1fe70 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 other functions
1fe80 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a return UTF-8..**
1fe90 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 .** ^These APIs
1fea0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 are only availab
1feb0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
1fec0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
1fed0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
1fee0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
1fef0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 _METADATA] C-pre
1ff00 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c processor symbol
1ff10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f ..**.** If two o
1ff20 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 r more threads c
1ff30 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 all one or more
1ff40 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
1ff50 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 s against the sa
1ff60 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 me.** prepared s
1ff70 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c tatement and col
1ff80 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 umn at the same
1ff90 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
1ffa0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 sults are.** und
1ffb0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 efined..**.** If
1ffc0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 two or more thr
1ffd0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 eads call one or
1ffe0 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 more.** [sqlite
1fff0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
20000 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 e_name | column
20010 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 metadata interfa
20020 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ces].** for the
20030 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
20040 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 tatement] and re
20050 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 sult column.** a
20060 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 t the same time
20070 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
20080 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
20090 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
200a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
200b0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 tabase_name(sqli
200c0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
200d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
200e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
200f0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 ase_name16(sqlit
20100 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
20110 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
20120 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
20130 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
20140 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 t*,int);.const v
20150 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
20160 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 umn_table_name16
20170 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
20180 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 nt);.const char
20190 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
201a0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 origin_name(sqli
201b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
201c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
201d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 te3_column_origi
201e0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 n_name16(sqlite3
201f0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a _stmt*,int);../*
20200 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
20210 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 clared Datatype
20220 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c Of A Query Resul
20230 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 t.**.** ^(The fi
20240 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
20250 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
20260 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 tement]..** If t
20270 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 his statement is
20280 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
20290 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 ement and the Nt
202a0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a h column of the.
202b0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 ** returned resu
202c0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b lt set of that [
202d0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 SELECT] is a tab
202e0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 le column (not a
202f0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 n.** expression
20300 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 or subquery) the
20310 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 n the declared t
20320 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ype of the table
20330 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 .** column is re
20340 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 turned.)^ ^If t
20350 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
20360 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
20370 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 is an.** express
20380 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c ion or subquery,
20390 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 then a NULL poi
203a0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
203b0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e ..** ^The return
203c0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 ed string is alw
203d0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 ays UTF-8 encode
203e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 d..**.** ^(For e
203f0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 xample, given th
20400 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
20410 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 a:.**.** CREATE
20420 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 TABLE t1(c1 VARI
20430 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 ANT);.**.** and
20440 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 the following st
20450 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f atement to be co
20460 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 mpiled:.**.** SE
20470 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 LECT c1 + 1, c1
20480 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 FROM t1;.**.** t
20490 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c his routine woul
204a0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 d return the str
204b0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f ing "VARIANT" fo
204c0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 r the second res
204d0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 ult.** column (i
204e0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c ==1), and a NULL
204f0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 pointer for the
20500 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f first result co
20510 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a lumn (i==0).)^.*
20520 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 *.** ^SQLite use
20530 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 s dynamic run-ti
20540 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 me typing. ^So
20550 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 just because a c
20560 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c olumn.** is decl
20570 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 ared to contain
20580 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 a particular typ
20590 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 e does not mean
205a0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 that the.** data
205b0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 stored in that
205c0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 column is of the
205d0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 declared type.
205e0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 SQLite is.** st
205f0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 rongly typed, bu
20600 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 t the typing is
20610 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 dynamic not stat
20620 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 ic. ^Type.** is
20630 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
20640 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 individual valu
20650 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 es, not with the
20660 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 containers.** u
20670 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 sed to hold thos
20680 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e e values..*/.con
20690 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
206a0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
206b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
206c0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
206d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
206e0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 decltype16(sqlit
206f0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a e3_stmt*,int);..
20700 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
20710 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 Evaluate An SQL
20720 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 Statement.**.**
20730 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 After a [prepare
20740 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 d statement] has
20750 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 been prepared u
20760 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b sing either.** [
20770 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
20780 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
20790 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
207a0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 ] or one of the
207b0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
207c0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 aces [sqlite3_pr
207d0 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c epare()] or [sql
207e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
207f0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ], this function
20800 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c .** must be call
20810 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 ed one or more t
20820 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 imes to evaluate
20830 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a the statement..
20840 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c **.** The detail
20850 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f s of the behavio
20860 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 r of the sqlite3
20870 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 _step() interfac
20880 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 e depend.** on w
20890 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 hether the state
208a0 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 ment was prepare
208b0 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 d using the newe
208c0 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 r "v2" interface
208d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
208e0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
208f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
20900 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6_v2()] or the o
20910 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 lder legacy.** i
20920 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 nterface [sqlite
20930 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 3_prepare()] and
20940 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
20950 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 e16()]. The use
20960 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 of the.** new "
20970 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 v2" interface is
20980 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
20990 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
209a0 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 s but the legacy
209b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 .** interface wi
209c0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 ll continue to b
209d0 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a e supported..**.
209e0 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 ** ^In the legac
209f0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 y interface, the
20a00 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 return value wi
20a10 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 ll be either [SQ
20a20 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b LITE_BUSY],.** [
20a30 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 SQLITE_DONE], [S
20a40 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c QLITE_ROW], [SQL
20a50 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b ITE_ERROR], or [
20a60 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a SQLITE_MISUSE]..
20a70 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 ** ^With the "v2
20a80 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 " interface, any
20a90 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 of the other [r
20aa0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a esult codes] or.
20ab0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
20ac0 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 ult codes] might
20ad0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 be returned as
20ae0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 well..**.** ^[SQ
20af0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 LITE_BUSY] means
20b00 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 that the databa
20b10 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e se engine was un
20b20 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 able to acquire
20b30 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
20b40 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 locks it needs t
20b50 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e o do its job. ^
20b60 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 If the statement
20b70 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a is a [COMMIT].*
20b80 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 * or occurs outs
20b90 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 ide of an explic
20ba0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
20bb0 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 then you can ret
20bc0 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d ry the.** statem
20bd0 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 ent. If the sta
20be0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 tement is not a
20bf0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 [COMMIT] and occ
20c00 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 urs within a.**
20c10 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 explicit transac
20c20 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 tion then you sh
20c30 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 ould rollback th
20c40 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 e transaction be
20c50 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 fore.** continui
20c60 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ng..**.** ^[SQLI
20c70 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 TE_DONE] means t
20c80 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e hat the statemen
20c90 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 t has finished e
20ca0 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 xecuting.** succ
20cb0 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 essfully. sqlit
20cc0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 e3_step() should
20cd0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 not be called a
20ce0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 gain on this vir
20cf0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
20d00 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 without first ca
20d10 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
20d20 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 eset()] to reset
20d30 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 the virtual.**
20d40 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 machine back to
20d50 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 its initial stat
20d60 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 e..**.** ^If the
20d70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 SQL statement b
20d80 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 eing executed re
20d90 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 turns any data,
20da0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 then [SQLITE_ROW
20db0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 ].** is returned
20dc0 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 each time a new
20dd0 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 row of data is
20de0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 ready for proces
20df0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 sing by the.** c
20e00 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 aller. The value
20e10 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 s may be accesse
20e20 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c d using the [col
20e30 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
20e40 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 ions]..** sqlite
20e50 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 3_step() is call
20e60 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 ed again to retr
20e70 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f ieve the next ro
20e80 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a w of data..**.**
20e90 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d ^[SQLITE_ERROR]
20ea0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 means that a ru
20eb0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 n-time error (su
20ec0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 ch as a constrai
20ed0 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 nt.** violation)
20ee0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 has occurred.
20ef0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 sqlite3_step() s
20f00 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c hould not be cal
20f10 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 led again on.**
20f20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 the VM. More inf
20f30 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 ormation may be
20f40 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 found by calling
20f50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
20f60 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 ()]..** ^With th
20f70 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
20f80 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 ce, a more speci
20f90 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 fic error code (
20fa0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 for example,.**
20fb0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
20fc0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 T], [SQLITE_SCHE
20fd0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 MA], [SQLITE_COR
20fe0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f RUPT], and so fo
20ff0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f rth).** can be o
21000 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 btained by calli
21010 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
21020 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b t()] on the.** [
21030 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
21040 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 nt]. ^In the "v
21050 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 2" interface,.**
21060 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 the more specif
21070 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 ic error code is
21080 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
21090 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ly by sqlite3_st
210a0 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c ep()..**.** [SQL
210b0 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e ITE_MISUSE] mean
210c0 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 s that the this
210d0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c routine was call
210e0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 ed inappropriate
210f0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 ly..** Perhaps i
21100 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 t was called on
21110 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
21120 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a ement] that has.
21130 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 ** already been
21140 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
21150 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f e | finalized] o
21160 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 r on one that ha
21170 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 d.** previously
21180 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
21190 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 _ERROR] or [SQLI
211a0 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 TE_DONE]. Or it
211b0 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 could.** be the
211c0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 case that the s
211d0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
211e0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 nection is being
211f0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a used by two or.
21200 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 ** more threads
21210 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 at the same mome
21220 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a nt in time..**.*
21230 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 * <b>Goofy Inter
21240 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 face Alert:</b>
21250 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e In the legacy in
21260 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c terface, the sql
21270 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 ite3_step().** A
21280 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e PI always return
21290 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f s a generic erro
212a0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f r code, [SQLITE_
212b0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e ERROR], followin
212c0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f g any.** error o
212d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
212e0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c E_BUSY] and [SQL
212f0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f ITE_MISUSE]. Yo
21300 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b u must call.** [
21310 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
21320 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
21330 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 alize()] in orde
21340 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 r to find one of
21350 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
21360 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 [error codes] t
21370 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 hat better descr
21380 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a ibes the error..
21390 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ** We admit that
213a0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 this is a goofy
213b0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 design. The pr
213c0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 oblem has been f
213d0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ixed.** with the
213e0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e "v2" interface.
213f0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 If you prepare
21400 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c all of your SQL
21410 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 statements.** u
21420 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
21430 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
21440 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
21450 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 repare16_v2()] i
21460 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 nstead.** of the
21470 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 legacy [sqlite3
21480 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
21490 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
214a0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 16()] interfaces
214b0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f ,.** then the mo
214c0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 re specific [err
214d0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 or codes] are re
214e0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a turned directly.
214f0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ** by sqlite3_st
21500 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f ep(). The use o
21510 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 f the "v2" inter
21520 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
21530 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ded..*/.int sqli
21540 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 te3_step(sqlite3
21550 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
21560 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
21570 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
21580 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a result set.**.*
21590 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
215a0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 74 68 65 ata_count(P) the
215b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
215c0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6f 66 20 ns in the.** of
215d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
215e0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
215f0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69 6e 74 ement] P..*/.int
21600 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
21610 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
21620 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
21630 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
21640 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
21650 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
21660 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
21670 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e ^(Every value in
21680 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 SQLite has one
21690 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e of five fundamen
216a0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a tal datatypes:.*
216b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
216c0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 > 64-bit signed
216d0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 integer.** <li>
216e0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 64-bit IEEE floa
216f0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
21700 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 r.** <li> string
21710 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a .** <li> BLOB.**
21720 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f <li> NULL.** </
21730 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ul>)^.**.** Thes
21740 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
21750 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
21760 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
21770 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
21780 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
21790 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
217a0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
217b0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
217c0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
217d0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
217e0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
217f0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
21800 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
21810 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
21820 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
21830 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
21840 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
21850 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
21860 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
21870 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
21880 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
21890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
218a0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
218b0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
218c0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
218d0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
218e0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
218f0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
21900 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
21910 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
21920 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
21930 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
21940 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
21950 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 m A Query.** KEY
21960 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 WORDS: {column a
21970 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d ccess functions}
21980 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
21990 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 tines form the "
219a0 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 result set" inte
219b0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rface..**.** ^Th
219c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
219d0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
219e0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 about a single c
219f0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 olumn of the cur
21a00 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 rent.** result r
21a10 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
21a20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 ^In every case t
21a30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
21a40 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
21a50 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
21a60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
21a70 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
21a80 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
21a90 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
21aa0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
21ab0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
21ac0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
21ad0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
21ae0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
21af0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
21b00 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
21b10 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
21b20 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
21b30 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
21b40 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 urned. ^The left
21b50 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
21b60 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
21b70 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
21b80 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 * ^The number of
21b90 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
21ba0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 result can be de
21bb0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a termined using.*
21bc0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
21bd0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a n_count()]..**.*
21be0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
21bf0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
21c00 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
21c10 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
21c20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c or if the.** col
21c30 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 umn index is out
21c40 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 of range, the r
21c50 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
21c60 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ed..** These rou
21c70 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 tines may only b
21c80 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 e called when th
21c90 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
21ca0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
21cb0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
21cc0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
21cd0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a OW] and neither.
21ce0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
21cf0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 t()] nor [sqlite
21d00 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 3_finalize()] ha
21d10 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 ve been called s
21d20 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 ubsequently..**
21d30 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 If any of these
21d40 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
21d50 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
21d60 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
21d70 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
21d80 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
21d90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21da0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a has returned.**
21db0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
21dc0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
21dd0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 W], the results
21de0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
21df0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 * If [sqlite3_st
21e00 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
21e10 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
21e20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
21e30 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 )].** are called
21e40 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e from a differen
21e50 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 t thread while a
21e60 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
21e70 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 ines.** are pend
21e80 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
21e90 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
21ea0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
21eb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
21ec0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ype() routine re
21ed0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 turns the.** [SQ
21ee0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
21ef0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
21f00 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
21f10 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
21f20 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
21f30 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
21f40 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
21f50 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
21f60 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
21f70 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
21f80 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
21f90 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
21fa0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a LL]. The value.
21fb0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
21fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
21fd0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 pe() is only mea
21fe0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 ningful if no ty
21ff0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e pe.** conversion
22000 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 s have occurred
22010 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c as described bel
22020 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 ow. After a typ
22030 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a e conversion,.**
22040 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
22050 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
22060 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
22070 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 undefined. Futu
22080 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f re.** versions o
22090 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 f SQLite may cha
220a0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 nge the behavior
220b0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 of sqlite3_colu
220c0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c mn_type().** fol
220d0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f lowing a type co
220e0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
220f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
22100 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
22110 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
22120 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
22130 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
22140 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
22150 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
22160 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
22170 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
22180 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
22190 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
221a0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
221b0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
221c0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
221d0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
221e0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
221f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
22200 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
22210 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
22220 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
22230 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
22240 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
22250 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
22260 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
22270 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
22280 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
22290 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
222a0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
222b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54 68 65 string..** ^The
222c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
222d0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
222e0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
222f0 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a ator at the end.
22300 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 ** of the string
22310 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a . ^For clarity:
22320 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
22330 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ned is the numbe
22340 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e r of.** bytes in
22350 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 the string, not
22360 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
22370 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a haracters..**.**
22380 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e ^Strings return
22390 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
223a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 lumn_text() and
223b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
223c0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e ext16(),.** even
223d0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 empty strings,
223e0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 are always zero
223f0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 terminated. ^Th
22400 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 e return.** valu
22410 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 e from sqlite3_c
22420 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 olumn_blob() for
22430 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
22440 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 LOB is an arbitr
22450 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 ary.** pointer,
22460 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 possibly even a
22470 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
22480 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
22490 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
224a0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d ) routine is sim
224b0 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f ilar to sqlite3_
224c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a column_bytes().*
224d0 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 * but leaves the
224e0 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 result in UTF-1
224f0 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 6 in native byte
22500 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f order instead o
22510 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54 68 65 f UTF-8..** ^The
22520 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
22530 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 is not included
22540 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a in this count..
22550 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 **.** ^The objec
22560 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 t returned by [s
22570 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
22580 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 lue()] is an.**
22590 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
225a0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
225b0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 ct. An unprotec
225c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
225d0 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 e object.** may
225e0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
225f0 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f h [sqlite3_bind_
22600 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
22610 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
22620 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ue()]..** If the
22630 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
22640 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
22650 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
22660 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
22670 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
22680 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 sed in any other
22690 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 way, including
226a0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 calls.** to rout
226b0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 ines like [sqlit
226c0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c e3_value_int()],
226d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
226e0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
226f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
22700 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 tes()], then the
22710 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
22720 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 efined..**.** Th
22730 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 ese routines att
22740 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 empt to convert
22750 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 the value where
22760 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 appropriate. ^F
22770 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 or.** example, i
22780 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 f the internal r
22790 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 epresentation is
227a0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 FLOAT and a tex
227b0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 t result.** is r
227c0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 equested, [sqlit
227d0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 e3_snprintf()] i
227e0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c s used internall
227f0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 y to perform the
22800 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 .** conversion a
22810 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e utomatically. ^
22820 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 (The following t
22830 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 able details the
22840 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 conversions.**
22850 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 that are applied
22860 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
22870 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 ote>.** <table b
22880 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 order="1">.** <t
22890 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c r><th> Internal<
228a0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 br>Type <th> Req
228b0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c uested<br>Type <
228c0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a th> Conversion.
228d0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 **.** <tr><td>
228e0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 NULL <td> INT
228f0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 EGER <td> Resu
22900 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c lt is 0.** <tr><
22910 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
22920 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
22930 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a Result is 0.0.*
22940 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
22950 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
22960 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
22970 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
22980 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
22990 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
229a0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
229b0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
229c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
229d0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 ER <td> FLOAT
229e0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
229f0 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 from integer to
22a00 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
22a10 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
22a20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
22a30 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
22a40 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a f the integer.**
22a50 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
22a60 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 R <td> BLOB
22a70 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 <td> Same as I
22a80 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 NTEGER->TEXT.**
22a90 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
22aa0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
22ab0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
22ac0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 om float to inte
22ad0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ger.** <tr><td>
22ae0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
22af0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
22b00 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
22b10 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 the float.** <tr
22b20 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
22b30 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
22b40 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 d> Same as FLOAT
22b50 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
22b60 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
22b70 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
22b80 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 Use atoi().** <t
22b90 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
22ba0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
22bb0 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a td> Use atof().*
22bc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
22bd0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
22be0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 <td> No chang
22bf0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 e.** <tr><td> B
22c00 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOB <td> INTE
22c10 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 GER <td> Conve
22c20 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 rt to TEXT then
22c30 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 use atoi().** <t
22c40 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
22c50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
22c60 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 td> Convert to T
22c70 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f EXT then use ato
22c80 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 f().** <tr><td>
22c90 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 BLOB <td>
22ca0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 TEXT <td> Add
22cb0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 a zero terminat
22cc0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 or if needed.**
22cd0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c </table>.** </bl
22ce0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a ockquote>)^.**.*
22cf0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 * The table abov
22d00 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 e makes referenc
22d10 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 e to standard C
22d20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e library function
22d30 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 s atoi().** and
22d40 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 atof(). SQLite
22d50 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 does not really
22d60 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 use these functi
22d70 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 ons. It has its
22d80 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 .** own equivale
22d90 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 nt internal rout
22da0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 ines. The atoi(
22db0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d ) and atof() nam
22dc0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 es are.** used i
22dd0 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 n the table for
22de0 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 brevity and beca
22df0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d use they are fam
22e00 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a iliar to most.**
22e10 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a C programmers..
22e20 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 **.** ^Note that
22e30 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 when type conve
22e40 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f rsions occur, po
22e50 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
22e60 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c by prior.** call
22e70 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
22e80 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 umn_blob(), sqli
22e90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
22ea0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c ), and/or.** sql
22eb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
22ec0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 16() may be inva
22ed0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 5e 28 54 79 lidated..** ^(Ty
22ee0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 pe conversions a
22ef0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c nd pointer inval
22f00 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f idations might o
22f10 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ccur.** in the f
22f20 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a ollowing cases:.
22f30 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
22f40 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
22f50 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 ontent is a BLOB
22f60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
22f70 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a umn_text() or.**
22f80 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
22f90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 lumn_text16() is
22fa0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f called. A zero
22fb0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 -terminator migh
22fc0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 t.** need t
22fd0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 o be added to th
22fe0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a e string.</li>.*
22ff0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 * <li> The initi
23000 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 al content is UT
23010 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c F-8 text and sql
23020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
23030 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 s16() or.**
23040 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
23050 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
23060 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 ed. The content
23070 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
23080 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 ed.** to UT
23090 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c F-16.</li>.** <l
230a0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
230b0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 ontent is UTF-16
230c0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
230d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
230e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
230f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
23100 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
23110 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
23120 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
23130 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c to UTF-8.</l
23140 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a i>.** </ul>)^.**
23150 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 .** ^Conversions
23160 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 between UTF-16b
23170 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 e and UTF-16le a
23180 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 re always done i
23190 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a n place and do.*
231a0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 * not invalidate
231b0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 a prior pointer
231c0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 , though of cour
231d0 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f se the content o
231e0 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 f the buffer.**
231f0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 that the prior p
23200 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f ointer points to
23210 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 will have been
23220 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 modified. Other
23230 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e kinds.** of con
23240 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 version are done
23250 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 in place when i
23260 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 t is possible, b
23270 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 ut sometimes the
23280 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 y.** are not pos
23290 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f sible and in tho
232a0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 se cases prior p
232b0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 ointers are inva
232c0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e lidated..**.** ^
232d0 28 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 (The safest and
232e0 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d easiest to remem
232f0 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f ber policy is to
23300 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f invoke these ro
23310 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 utines.** in one
23320 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
23330 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 g ways:.**.** <u
23340 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 l>.** <li>sqlit
23350 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
23360 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
23370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
23380 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 s()</li>.** <li
23390 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
233a0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 blob() followed
233b0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
233c0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
233d0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
233e0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 olumn_text16() f
233f0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
23400 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
23410 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 6()</li>.** </ul
23420 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 >)^.**.** In oth
23430 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 er words, you sh
23440 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 ould call sqlite
23450 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
23460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
23470 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 mn_blob(), or sq
23480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
23490 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 t16() first to f
234a0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a orce the result.
234b0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 ** into the desi
234c0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e red format, then
234d0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
234e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f column_bytes() o
234f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
23500 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f umn_bytes16() to
23510 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f find the size o
23520 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 f the result. D
23530 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a o not mix calls.
23540 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ** to sqlite3_co
23550 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 lumn_text() or s
23560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
23570 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 ob() with calls
23580 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
23590 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 lumn_bytes16(),
235a0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 and do not mix c
235b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
235c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a column_text16().
235d0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f ** with calls to
235e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
235f0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e bytes()..**.** ^
23600 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 The pointers ret
23610 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 urned are valid
23620 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e until a type con
23630 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 version occurs a
23640 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 s.** described a
23650 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b bove, or until [
23660 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
23670 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
23680 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
23690 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
236a0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 is called. ^The
236b0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 memory space us
236c0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e ed to hold strin
236d0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 gs.** and BLOBs
236e0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 is freed automat
236f0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e ically. Do <b>n
23700 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 ot</b> pass the
23710 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
23720 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f d.** [sqlite3_co
23730 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 lumn_blob()], [s
23740 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
23750 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f xt()], etc. into
23760 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
23770 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 e()]..**.** ^(If
23780 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
23790 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 tion error occur
237a0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 s during the eva
237b0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a luation of any.*
237c0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 * of these routi
237d0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 nes, a default v
237e0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 alue is returned
237f0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 . The default v
23800 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 alue.** is eithe
23810 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c r the integer 0,
23820 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f the floating po
23830 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 int number 0.0,
23840 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 or a NULL.** poi
23850 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e nter. Subsequen
23860 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 t calls to [sqli
23870 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 te3_errcode()] w
23880 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 ill return.** [S
23890 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a QLITE_NOMEM].)^.
238a0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 */.const void *s
238b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
238c0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
238d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
238e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
238f0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 bytes(sqlite3_st
23900 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
23910 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
23920 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 mn_bytes16(sqlit
23930 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
23940 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 ol);.double sqli
23950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c te3_column_doubl
23960 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
23970 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 int iCol);.int
23980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 sqlite3_column_i
23990 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
239a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c , int iCol);.sql
239b0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
239c0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 e3_column_int64(
239d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
239e0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 nt iCol);.const
239f0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 unsigned char *s
23a00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
23a10 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a xt(sqlite3_stmt*
23a20 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e , int iCol);.con
23a30 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
23a40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 _column_text16(s
23a50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
23a60 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c t iCol);.int sql
23a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
23a80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
23a90 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 int iCol);.sqlit
23aa0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 e3_value *sqlite
23ab0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 3_column_value(s
23ac0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
23ad0 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t iCol);../*.**
23ae0 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f CAPI3REF: Destro
23af0 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 y A Prepared Sta
23b00 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
23b10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
23b20 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 _finalize() func
23b30 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
23b40 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 o delete a [prep
23b50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
23b60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 74 61 74 .** ^If the stat
23b70 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 ement was execut
23b80 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 ed successfully
23b90 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 or not executed
23ba0 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 at all, then.**
23bb0 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 SQLITE_OK is ret
23bc0 75 72 6e 65 64 2e 20 5e 49 66 20 65 78 65 63 75 urned. ^If execu
23bd0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 tion of the stat
23be0 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 ement failed the
23bf0 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 n an.** [error c
23c00 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 ode] or [extende
23c10 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 d error code] is
23c20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
23c30 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 ^This routine c
23c40 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 an be called at
23c50 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 any point during
23c60 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f the execution o
23c70 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 f the.** [prepar
23c80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
23c90 5e 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 ^If the virtual
23ca0 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a machine has not.
23cb0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 ** completed exe
23cc0 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 cution when this
23cd0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c routine is call
23ce0 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 ed, that is like
23cf0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 .** encountering
23d00 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 an error or an
23d10 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
23d20 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e pt | interrupt].
23d30 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74 65 20 .** ^Incomplete
23d40 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 updates may be r
23d50 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 olled back and t
23d60 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 ransactions canc
23d70 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 eled,.** dependi
23d80 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d ng on the circum
23d90 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 stances, and the
23da0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d .** [error code]
23db0 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 returned will b
23dc0 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d e [SQLITE_ABORT]
23dd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
23de0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 _finalize(sqlite
23df0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
23e00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23e10 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 Reset A Prepare
23e20 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
23e30 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ct.**.** The sql
23e40 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e ite3_reset() fun
23e50 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 ction is called
23e60 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 to reset a [prep
23e70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
23e80 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 ** object back t
23e90 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 o its initial st
23ea0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 ate, ready to be
23eb0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a re-executed..**
23ec0 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d ^Any SQL statem
23ed0 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 ent variables th
23ee0 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f at had values bo
23ef0 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e und to them usin
23f00 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 g.** the [sqlite
23f10 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 3_bind_blob | sq
23f20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 lite3_bind_*() A
23f30 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 PI] retain their
23f40 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 values..** Use
23f50 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 [sqlite3_clear_b
23f60 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 indings()] to re
23f70 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 set the bindings
23f80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 ..**.** ^The [sq
23f90 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
23fa0 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 interface resets
23fb0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
23fc0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 tatement] S.** b
23fd0 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e ack to the begin
23fe0 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 ning of its prog
23ff0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ram..**.** ^If t
24000 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
24010 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
24020 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 step(S)] for the
24030 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
24040 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 atement] S retur
24050 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d ned [SQLITE_ROW]
24060 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 or [SQLITE_DONE
24070 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c ],.** or if [sql
24080 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 ite3_step(S)] ha
24090 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 s never before b
240a0 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c een called on S,
240b0 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 .** then [sqlite
240c0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 3_reset(S)] retu
240d0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e rns [SQLITE_OK].
240e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d .**.** ^If the m
240f0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
24100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
24110 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 (S)] for the.**
24120 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
24130 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 ent] S indicated
24140 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a an error, then.
24150 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
24160 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e t(S)] returns an
24170 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
24180 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a ror code]..**.**
24190 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 ^The [sqlite3_r
241a0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 eset(S)] interfa
241b0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e ce does not chan
241c0 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a ge the values.**
241d0 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 of any [sqlite3
241e0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 _bind_blob|bindi
241f0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 ngs] on the [pre
24200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
24210 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 S..*/.int sqlit
24220 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 e3_reset(sqlite3
24230 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
24240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
24250 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 Create Or Redefi
24260 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 ne SQL Functions
24270 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 .** KEYWORDS: {f
24280 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
24290 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 routines}.** KE
242a0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
242b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
242c0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 function}.** KE
242d0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
242e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
242f0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a functions}.**.*
24300 2a 20 5e 54 68 65 73 65 20 74 77 6f 20 66 75 6e * ^These two fun
24310 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 ctions (collecti
24320 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 vely known as "f
24330 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
24340 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 routines").** a
24350 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 re used to add S
24360 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
24370 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f aggregates or to
24380 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 redefine the be
24390 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 havior.** of exi
243a0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 sting SQL functi
243b0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
243c0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 s. The only dif
243d0 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 ference between
243e0 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 the.** two is th
243f0 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 at the second pa
24400 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d rameter, the nam
24410 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 e of the (scalar
24420 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a ) function or.**
24430 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 aggregate, is e
24440 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 ncoded in UTF-8
24450 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
24460 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e te_function() an
24470 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 d UTF-16.** for
24480 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
24490 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a unction16()..**.
244a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 ** ^The first pa
244b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
244c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
244d0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 ion] to which th
244e0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f e SQL.** functio
244f0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 n is to be added
24500 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 . ^If an applic
24510 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 ation uses more
24520 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 than one databas
24530 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
24540 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e then application
24550 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
24560 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 ctions must be a
24570 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 dded.** to each
24580 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
24590 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a ion separately..
245a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
245b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
245c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 e name of the SQ
245d0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 L function to be
245e0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 created or.** r
245f0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 edefined. ^The
24600 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 length of the na
24610 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f me is limited to
24620 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 255 bytes, excl
24630 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 usive of.** the
24640 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e zero-terminator.
24650 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 Note that the
24660 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 name length limi
24670 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e t is in bytes, n
24680 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 ot.** characters
24690 2e 20 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 . ^Any attempt
246a0 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 to create a func
246b0 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 tion with a long
246c0 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 er name.** will
246d0 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 result in [SQLIT
246e0 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 E_ERROR] being r
246f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
24700 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
24710 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 ter (nArg).** is
24720 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 the number of a
24730 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 rguments that th
24740 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
24750 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 r.** aggregate t
24760 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 akes. ^If this p
24770 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 arameter is -1,
24780 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e then the SQL fun
24790 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
247a0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 egate may take a
247b0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 ny number of arg
247c0 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 uments between 0
247d0 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a and the limit.*
247e0 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 * set by [sqlite
247f0 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 3_limit]([SQLITE
24800 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
24810 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 ARG]). If the t
24820 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hird.** paramete
24830 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d r is less than -
24840 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 1 or greater tha
24850 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 n 127 then the b
24860 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e ehavior is.** un
24870 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 defined..**.** T
24880 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
24890 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 ter, eTextRep, s
248a0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a pecifies what.**
248b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 [SQLITE_UTF8 |
248c0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 text encoding] t
248d0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e his SQL function
248e0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 prefers for.**
248f0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 its parameters.
24900 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f Any SQL functio
24910 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
24920 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 should be able
24930 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 to work.** work
24940 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d with UTF-8, UTF-
24950 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 16le, or UTF-16b
24960 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 e. But some imp
24970 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 lementations may
24980 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 be.** more effi
24990 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 cient with one e
249a0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f ncoding than ano
249b0 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 ther. ^An appli
249c0 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e cation may.** in
249d0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 voke sqlite3_cre
249e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f ate_function() o
249f0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
24a00 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 _function16() mu
24a10 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 ltiple.** times
24a20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 with the same fu
24a30 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 nction but with
24a40 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 different values
24a50 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a of eTextRep..**
24a60 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 ^When multiple
24a70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
24a80 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
24a90 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 tion are availab
24aa0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 le, SQLite.** wi
24ab0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 ll pick the one
24ac0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 that involves th
24ad0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f e least amount o
24ae0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f f data conversio
24af0 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 n..** If there i
24b00 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 s only a single
24b10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
24b20 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 hich does not ca
24b30 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 re what text.**
24b40 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
24b50 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 , then the fourt
24b60 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c h argument shoul
24b70 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 d be [SQLITE_ANY
24b80 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 ]..**.** ^(The f
24b90 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 ifth parameter i
24ba0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 s an arbitrary p
24bb0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 ointer. The imp
24bc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
24bd0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 he.** function c
24be0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 an gain access t
24bf0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 o this pointer u
24c00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 sing [sqlite3_us
24c10 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a er_data()].)^.**
24c20 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c .** The seventh,
24c30 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 eighth and nint
24c40 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 h parameters, xF
24c50 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 unc, xStep and x
24c60 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f Final, are.** po
24c70 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 inters to C-lang
24c80 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 uage functions t
24c90 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
24ca0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
24cb0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 r.** aggregate.
24cc0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 ^A scalar SQL fu
24cd0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
24ce0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
24cf0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a n of the xFunc.*
24d00 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b * callback only;
24d10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 NULL pointers s
24d20 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 hould be passed
24d30 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 as the xStep and
24d40 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d xFinal.** param
24d50 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 eters. ^An aggre
24d60 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
24d70 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d n requires an im
24d80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
24d90 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 xStep.** and xFi
24da0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f nal and NULL sho
24db0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f uld be passed fo
24dc0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c r xFunc. ^To del
24dd0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a ete an existing.
24de0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ** SQL function
24df0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 or aggregate, pa
24e00 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 ss NULL for all
24e10 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 three function c
24e20 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 allbacks..**.**
24e30 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 ^It is permitted
24e40 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c to register mul
24e50 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
24e60 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
24e70 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 e.** functions w
24e80 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ith the same nam
24e90 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 e but with eithe
24ea0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 r differing numb
24eb0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 ers of.** argume
24ec0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 nts or differing
24ed0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
24ee0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c encodings. ^SQL
24ef0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
24f00 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
24f10 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f on that most clo
24f20 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 sely matches the
24f30 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 way in which th
24f40 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f e.** SQL functio
24f50 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 n is used. ^A f
24f60 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
24f70 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f tation with a no
24f80 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 n-negative.** nA
24f90 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rg parameter is
24fa0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 a better match t
24fb0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 han a function i
24fc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
24fd0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 th.** a negative
24fe0 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 nArg. ^A funct
24ff0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 ion where the pr
25000 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
25010 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 oding.** matches
25020 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
25030 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 coding is a bett
25040 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e er.** match than
25050 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 a function wher
25060 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 e the encoding i
25070 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a s different. .*
25080 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 * ^A function wh
25090 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
250a0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 difference is b
250b0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 etween UTF16le a
250c0 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 nd UTF16be.** is
250d0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 a closer match
250e0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
250f0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
25100 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
25110 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 .** between UTF8
25120 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a and UTF16..**.*
25130 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 * ^Built-in func
25140 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 tions may be ove
25150 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 rloaded by new a
25160 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
25170 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a ed functions..**
25180 20 5e 54 68 65 20 66 69 72 73 74 20 61 70 70 6c ^The first appl
25190 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
251a0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
251b0 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 given name overr
251c0 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c ides all.** buil
251d0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 t-in functions i
251e0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 n the same [data
251f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
25200 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e with the same n
25210 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73 65 71 75 ame..** ^Subsequ
25220 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d ent application-
25230 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
25240 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 s of the same na
25250 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 me only override
25260 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 .** prior appli
25270 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
25280 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 unctions that ar
25290 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 e an exact match
252a0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 for the.** numb
252b0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 er of parameters
252c0 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 and preferred e
252d0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e ncoding..**.** ^
252e0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 An application-d
252f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
25300 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 is permitted to
25310 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 call other.** SQ
25320 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e Lite interfaces.
25330 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 However, such
25340 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a calls must not.*
25350 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 * close the data
25360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
25370 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 nor finalize or
25380 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 reset the prepar
25390 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
253a0 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e in which the fun
253b0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
253c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
253d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
253e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
253f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
25400 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 FunctionName,.
25410 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 int nArg,. int
25420 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 eTextRep,. void
25430 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 *pApp,. void (
25440 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f *xFunc)(sqlite3_
25450 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
25460 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
25470 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 void (*xStep)(s
25480 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
25490 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
254a0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
254b0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 Final)(sqlite3_c
254c0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 ontext*).);.int
254d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
254e0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c unction16(. sql
254f0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
25500 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f t void *zFunctio
25510 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
25520 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
25530 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
25540 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
25550 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
25560 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
25570 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
25580 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
25590 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
255a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
255b0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
255c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
255d0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ).);../*.** CAPI
255e0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 3REF: Text Encod
255f0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ings.**.** These
25600 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 constant define
25610 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 integer codes t
25620 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 hat represent th
25630 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 e various.** tex
25640 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 t encodings supp
25650 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e orted by SQLite.
25660 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
25670 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 TE_UTF8
25680 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
25690 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 TE_UTF16LE
256a0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
256b0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 TE_UTF16BE
256c0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
256d0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 TE_UTF16
256e0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 4 /* Use na
256f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
25700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
25710 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 E_ANY
25720 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
25730 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
25740 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
25750 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c SQLITE_UTF16_AL
25760 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 IGNED 8 /* s
25770 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
25780 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a llation only */.
25790 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
257a0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 Deprecated Func
257b0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 tions.** DEPRECA
257c0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TED.**.** These
257d0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 functions are [d
257e0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 eprecated]. In
257f0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 order to maintai
25800 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 n.** backwards c
25810 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
25820 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 h older code, th
25830 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f ese functions co
25840 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 ntinue .** to be
25850 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 supported. How
25860 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 ever, new applic
25870 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 ations should av
25880 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f oid.** the use o
25890 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
258a0 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f s. To help enco
258b0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 urage people to
258c0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 avoid.** using t
258d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 hese functions,
258e0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 we are not going
258f0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 to tell you wha
25900 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 t they do..*/.#i
25910 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 fndef SQLITE_OMI
25920 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c T_DEPRECATED.SQL
25930 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
25940 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 nt sqlite3_aggre
25950 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 gate_count(sqlit
25960 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
25970 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
25980 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 int sqlite3_expi
25990 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 red(sqlite3_stmt
259a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 *);.SQLITE_DEPRE
259b0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
259c0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 3_transfer_bindi
259d0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
259e0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a *, sqlite3_stmt*
259f0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
25a00 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
25a10 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 _global_recover(
25a20 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 void);.SQLITE_DE
25a30 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 PRECATED void sq
25a40 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 lite3_thread_cle
25a50 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 anup(void);.SQLI
25a60 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
25a70 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 t sqlite3_memory
25a80 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 _alarm(void(*)(v
25a90 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
25aa0 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 64,int),void*,sq
25ab0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 lite3_int64);.#e
25ac0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
25ad0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 3REF: Obtaining
25ae0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 SQL Function Par
25af0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a ameter Values.**
25b00 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 .** The C-langua
25b10 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ge implementatio
25b20 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f n of SQL functio
25b30 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
25b40 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 s uses.** this s
25b50 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 et of interface
25b60 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 routines to acce
25b70 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 ss the parameter
25b80 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 values on.** th
25b90 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 e function or ag
25ba0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 gregate..**.** T
25bb0 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 he xFunc (for sc
25bc0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 alar functions)
25bd0 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 or xStep (for ag
25be0 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 gregates) parame
25bf0 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 ters.** to [sqli
25c00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
25c10 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ion()] and [sqli
25c20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
25c30 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 ion16()].** defi
25c40 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 ne callbacks tha
25c50 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
25c60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
25c70 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a d aggregates..**
25c80 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 The 4th paramet
25c90 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c er to these call
25ca0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 backs is an arra
25cb0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
25cc0 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 .** [protected s
25cd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
25ce0 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 jects. There is
25cf0 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 one [sqlite3_va
25d00 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a lue] object for.
25d10 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 ** each paramete
25d20 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e r to the SQL fun
25d30 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f ction. These ro
25d40 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 utines are used
25d50 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 to.** extract va
25d60 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 lues from the [s
25d70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
25d80 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 jects..**.** The
25d90 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
25da0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 only with [prot
25db0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
25dc0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
25dd0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 Any attempt to
25de0 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e use these routin
25df0 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 es on an [unprot
25e00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
25e10 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 lue].** object r
25e20 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 esults in undefi
25e30 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
25e40 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
25e50 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 nes work just li
25e60 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e ke the correspon
25e70 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 ding [column acc
25e80 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a ess functions].*
25e90 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 * except that t
25ea0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 hese routines ta
25eb0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f ke a single [pro
25ec0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
25ed0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 alue] object.**
25ee0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 pointer instead
25ef0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 of a [sqlite3_st
25f00 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 mt*] pointer and
25f10 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 an integer colu
25f20 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a mn number..**.**
25f30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
25f40 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 lue_text16() int
25f50 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 erface extracts
25f60 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a a UTF-16 string.
25f70 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 ** in the native
25f80 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 byte-order of t
25f90 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e he host machine.
25fa0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
25fb0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
25fc0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 () and sqlite3_v
25fd0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 alue_text16le()
25fe0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 interfaces.** ex
25ff0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 tract UTF-16 str
26000 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 ings as big-endi
26010 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e an and little-en
26020 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c dian respectivel
26030 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 y..**.** ^(The s
26040 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d qlite3_value_num
26050 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 eric_type() inte
26060 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
26070 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 o apply.** numer
26080 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 ic affinity to t
26090 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 he value. This
260a0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 means that an at
260b0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 tempt is.** made
260c0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
260d0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 value to an inte
260e0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 ger or floating
260f0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 point. If.** su
26100 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ch a conversion
26110 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 is possible with
26120 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f out loss of info
26130 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 rmation (in othe
26140 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 r.** words, if t
26150 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 he value is a st
26160 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 ring that looks
26170 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a like a number).*
26180 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 * then the conve
26190 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d rsion is perform
261a0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e ed. Otherwise n
261b0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 o conversion occ
261c0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c urs..** The [SQL
261d0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
261e0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f tatype] after co
261f0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 nversion is retu
26200 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c rned.)^.**.** Pl
26210 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 ease pay particu
26220 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f lar attention to
26230 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 the fact that t
26240 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 he pointer retur
26250 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
26260 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
26270 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
26280 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a ue_text()], or.*
26290 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
262a0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 _text16()] can b
262b0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 e invalidated by
262c0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 a subsequent ca
262d0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
262e0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 3_value_bytes()]
262f0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
26300 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 _bytes16()], [sq
26310 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
26320 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
26330 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
26340 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ()]..**.** These
26350 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 routines must b
26360 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
26370 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 e same thread as
26380 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 .** the SQL func
26390 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 tion that suppli
263a0 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ed the [sqlite3_
263b0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 value*] paramete
263c0 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 rs..*/.const voi
263d0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
263e0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 _blob(sqlite3_va
263f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
26400 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 e3_value_bytes(s
26410 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
26420 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
26430 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 e_bytes16(sqlite
26440 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 3_value*);.doubl
26450 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
26460 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 double(sqlite3_v
26470 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
26480 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 te3_value_int(sq
26490 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 lite3_value*);.s
264a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
264b0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 ite3_value_int64
264c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
264d0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
264e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
264f0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 alue_text(sqlite
26500 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
26510 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
26520 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 alue_text16(sqli
26530 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
26540 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
26550 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
26560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
26570 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
26580 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
26590 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 6be(sqlite3_valu
265a0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
265b0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 _value_type(sqli
265c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
265d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e sqlite3_value_n
265e0 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 umeric_type(sqli
265f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a te3_value*);../*
26600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
26610 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 tain Aggregate F
26620 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a unction Context.
26630 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 69 **.** Implementi
26640 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 ons of aggregate
26650 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 SQL functions u
26660 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 se this.** routi
26670 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d ne to allocate m
26680 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e emory for storin
26690 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a g their state..*
266a0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
266b0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 time the sqlite3
266c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
266d0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 xt(C,N) routine
266e0 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f is called .** fo
266f0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 r a particular a
26700 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
26710 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c n, SQLite.** all
26720 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f ocates N of memo
26730 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 ry, zeroes out t
26740 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 hat memory, and
26750 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
26760 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 r.** to the new
26770 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f memory. ^On seco
26780 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
26790 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 t calls to.** sq
267a0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
267b0 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 context() for th
267c0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 e same aggregate
267d0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e function instan
267e0 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 ce,.** the same
267f0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e buffer is return
26800 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 ed. Sqlite3_agg
26810 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
26820 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 is normally.**
26830 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 called once for
26840 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 each invocation
26850 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c of the xStep cal
26860 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f lback and then o
26870 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 ne.** last time
26880 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 when the xFinal
26890 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
268a0 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 ked. ^(When no
268b0 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e rows match.** an
268c0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 aggregate query
268d0 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 , the xStep() ca
268e0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 llback of the ag
268f0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
26900 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
26910 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c on is never call
26920 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 ed and xFinal()
26930 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c is called exactl
26940 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 y once..** In th
26950 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 ose cases, sqlit
26960 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
26970 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 text() might be
26980 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a called for the.*
26990 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f * first time fro
269a0 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 m within xFinal(
269b0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ).)^.**.** ^The
269c0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
269d0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 e_context(C,N) r
269e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
269f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
26a00 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 N is.** less th
26a10 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
26a20 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f ero or if a memo
26a30 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f ry allocate erro
26a40 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 r occurs..**.**
26a50 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 ^(The amount of
26a60 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 space allocated
26a70 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 by sqlite3_aggre
26a80 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e gate_context(C,N
26a90 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e ) is.** determin
26aa0 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 ed by the N para
26ab0 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 meter on first s
26ac0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 uccessful call.
26ad0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a Changing the.**
26ae0 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 value of N in s
26af0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 ubsequent call t
26b00 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 o sqlite3_aggreg
26b10 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 ate_context() wi
26b20 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 thin.** the same
26b30 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
26b40 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c ion instance wil
26b50 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 l not resize the
26b60 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
26b70 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e ation.)^.**.** ^
26b80 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 SQLite automatic
26b90 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d ally frees the m
26ba0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 emory allocated
26bb0 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 by .** sqlite3_a
26bc0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
26bd0 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 () when the aggr
26be0 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 egate query conc
26bf0 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ludes..**.** The
26c00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
26c10 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 must be a copy
26c20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
26c30 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c e3_context | SQL
26c40 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 function contex
26c50 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 t] that is the f
26c60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a irst parameter.*
26c70 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f * to the xStep o
26c80 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 r xFinal callbac
26c90 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 k routine that i
26ca0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 mplements the ag
26cb0 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 gregate.** funct
26cc0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ion..**.** This
26cd0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
26ce0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
26cf0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
26d00 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 hich.** the aggr
26d10 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
26d20 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
26d30 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
26d40 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
26d50 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
26d60 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b t*, int nBytes);
26d70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
26d80 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 : User Data For
26d90 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
26da0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 ^The sqlite3_use
26db0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 r_data() interfa
26dc0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 ce returns a cop
26dd0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e y of.** the poin
26de0 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 ter that was the
26df0 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d pUserData param
26e00 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 eter (the 5th pa
26e10 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 rameter).** of t
26e20 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
26e30 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
26e40 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
26e50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
26e60 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 ()] routines tha
26e70 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 t originally.**
26e80 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 registered the a
26e90 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
26ea0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a ed function..**.
26eb0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
26ec0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
26ed0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
26ee0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
26ef0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
26f00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
26f10 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a is running..*/.
26f20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 void *sqlite3_us
26f30 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f er_data(sqlite3_
26f40 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a context*);../*.*
26f50 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
26f60 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
26f70 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a For Functions.**
26f80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
26f90 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
26fa0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 le() interface r
26fb0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 eturns a copy of
26fc0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 .** the pointer
26fd0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 to the [database
26fe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 connection] (th
26ff0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 e 1st parameter)
27000 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
27010 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
27020 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
27030 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
27040 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
27050 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
27060 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
27070 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
27080 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
27090 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 ion..*/.sqlite3
270a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 *sqlite3_context
270b0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 _db_handle(sqlit
270c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f e3_context*);../
270d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
270e0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 unction Auxiliar
270f0 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 y Data.**.** The
27100 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 following two f
27110 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 unctions may be
27120 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 used by scalar S
27130 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a QL functions to.
27140 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 ** associate met
27150 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d adata with argum
27160 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 ent values. If t
27170 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 he same value is
27180 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 passed to.** mu
27190 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f ltiple invocatio
271a0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 ns of the same S
271b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 QL function duri
271c0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 ng query executi
271d0 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d on, under.** som
271e0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 e circumstances
271f0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d the associated m
27200 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 etadata may be p
27210 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d reserved. This m
27220 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 ay.** be used, f
27230 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 or example, to a
27240 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 dd a regular-exp
27250 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 ression matching
27260 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 scalar.** funct
27270 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 ion. The compile
27280 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 d version of the
27290 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
272a0 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 ion is stored as
272b0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 .** metadata ass
272c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
272d0 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 SQL value passe
272e0 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 d as the regular
272f0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 expression.** p
27300 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d attern. The com
27310 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 piled regular ex
27320 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 pression can be
27330 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 reused on multip
27340 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e le.** invocation
27350 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
27360 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 nction so that t
27370 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 he original patt
27380 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f ern string.** do
27390 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
273a0 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 e recompiled on
273b0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e each invocation.
273c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
273d0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
273e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
273f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
27400 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a the metadata.**
27410 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 associated by t
27420 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
27430 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f uxdata() functio
27440 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 n with the Nth a
27450 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 rgument.** value
27460 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
27470 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
27480 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 tion. ^If no met
27490 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 adata has been e
274a0 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 ver.** been set
274b0 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 for the Nth argu
274c0 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 ment of the func
274d0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 tion, or if the
274e0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a corresponding.**
274f0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 function parame
27500 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 ter has changed
27510 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 since the meta-d
27520 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 ata was set,.**
27530 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 then sqlite3_get
27540 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72 _auxdata() retur
27550 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
27560 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 r..**.** ^The sq
27570 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
27580 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 a() interface sa
27590 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 ves the metadata
275a0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 .** pointed to b
275b0 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 y its 3rd parame
275c0 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 ter as the metad
275d0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 ata for the N-th
275e0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 .** argument of
275f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
27600 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
27610 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a . Subsequent.**
27620 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
27630 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_get_auxdata()
27640 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 might return thi
27650 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 s data, if it ha
27660 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 s.** not been de
27670 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 stroyed..** ^If
27680 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 it is not NULL,
27690 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f SQLite will invo
276a0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f ke the destructo
276b0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 r.** function gi
276c0 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 ven by the 4th p
276d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
276e0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
276f0 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 ) on.** the meta
27700 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f data when the co
27710 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 rresponding func
27720 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 tion parameter c
27730 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 hanges.** or whe
27740 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d n the SQL statem
27750 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 ent completes, w
27760 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 hichever comes f
27770 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 irst..**.** SQLi
27780 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 te is free to ca
27790 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f ll the destructo
277a0 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 r and drop metad
277b0 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 ata on any.** pa
277c0 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 rameter of any f
277d0 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 unction at any t
277e0 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 ime. ^The only
277f0 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 guarantee is tha
27800 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 t.** the destruc
27810 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c tor will be call
27820 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 ed before the me
27830 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 tadata is droppe
27840 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 d..**.** ^(In pr
27850 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 actice, metadata
27860 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 is preserved be
27870 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 tween function c
27880 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 alls for.** expr
27890 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 essions that are
278a0 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d constant at com
278b0 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 pile time. This
278c0 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c includes literal
278d0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b .** values and [
278e0 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a parameters].)^.*
278f0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
27900 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c nes must be call
27910 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
27920 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
27930 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 .** the SQL func
27940 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
27950 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
27960 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 3_get_auxdata(sq
27970 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
27980 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c int N);.void sql
27990 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
279a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
279b0 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c *, int N, void*,
279c0 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 void (*)(void*)
279d0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 );.../*.** CAPI3
279e0 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 REF: Constants D
279f0 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 efining Special
27a00 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 Destructor Behav
27a10 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ior.**.** These
27a20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 are special valu
27a30 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 es for the destr
27a40 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 uctor that is pa
27a50 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a ssed in as the.*
27a60 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 * final argument
27a70 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b to routines lik
27a80 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c e [sqlite3_resul
27a90 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 t_blob()]. ^If
27aa0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a the destructor.*
27ab0 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 * argument is SQ
27ac0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 LITE_STATIC, it
27ad0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 means that the c
27ae0 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 ontent pointer i
27af0 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e s constant.** an
27b00 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 d will never cha
27b10 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f nge. It does no
27b20 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 t need to be des
27b30 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a troyed. ^The.**
27b40 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
27b50 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 T value means th
27b60 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 at the content w
27b70 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 ill likely chang
27b80 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 e in.** the near
27b90 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 future and that
27ba0 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d SQLite should m
27bb0 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 ake its own priv
27bc0 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 ate copy of.** t
27bd0 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 he content befor
27be0 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a e returning..**.
27bf0 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 ** The typedef i
27c00 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 s necessary to w
27c10 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c ork around probl
27c20 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a ems in certain.*
27c30 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e * C++ compilers.
27c40 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 See ticket #21
27c50 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 91..*/.typedef v
27c60 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 oid (*sqlite3_de
27c70 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 structor_type)(v
27c80 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 oid*);.#define S
27c90 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 QLITE_STATIC
27ca0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 ((sqlite3_dest
27cb0 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 ructor_type)0).#
27cc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
27cd0 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 ANSIENT ((sqli
27ce0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 te3_destructor_t
27cf0 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 ype)-1)../*.** C
27d00 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 API3REF: Setting
27d10 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 The Result Of A
27d20 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a n SQL Function.*
27d30 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
27d40 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 nes are used by
27d50 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 the xFunc or xFi
27d60 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 nal callbacks th
27d70 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 at.** implement
27d80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
27d90 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 d aggregates. S
27da0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ee.** [sqlite3_c
27db0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
27dc0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
27dd0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
27de0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 ()].** for addit
27df0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
27e00 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 n..**.** These f
27e10 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 unctions work ve
27e20 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 ry much like the
27e30 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 [parameter bind
27e40 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a ing] family of.*
27e50 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 * functions used
27e60 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 to bind values
27e70 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 to host paramete
27e80 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 rs in prepared s
27e90 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 tatements..** Re
27ea0 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 fer to the [SQL
27eb0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d parameter] docum
27ec0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 entation for add
27ed0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
27ee0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
27ef0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
27f00 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 lob() interface
27f10 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 sets the result
27f20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 from.** an appli
27f30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
27f40 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
27f50 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e e BLOB whose con
27f60 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a tent is pointed.
27f70 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 ** to by the sec
27f80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e ond parameter an
27f90 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 d which is N byt
27fa0 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 es long where N
27fb0 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 is the.** third
27fc0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
27fd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
27fe0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 sult_zeroblob()
27ff0 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 interfaces set t
28000 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 he result of.**
28010 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
28020 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
28030 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f to be a BLOB co
28040 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 ntaining all zer
28050 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e o.** bytes and N
28060 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 bytes in size,
28070 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 where N is the v
28080 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 alue of the 2nd
28090 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
280a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
280b0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e sult_double() in
280c0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
280d0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 result from.**
280e0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
280f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
28100 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 to be a floating
28110 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 point value spe
28120 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 cified.** by its
28130 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2nd argument..*
28140 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
28150 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
28160 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 and sqlite3_res
28170 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 ult_error16() fu
28180 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 nctions.** cause
28190 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 the implemented
281a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f SQL function to
281b0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 throw an except
281c0 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ion..** ^SQLite
281d0 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 uses the string
281e0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
281f0 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 e.** 2nd paramet
28200 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 er of sqlite3_re
28210 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 sult_error() or
28220 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
28230 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 rror16().** as t
28240 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 he text of an er
28250 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 ror message. ^S
28260 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 QLite interprets
28270 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 the error.** me
28280 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f ssage string fro
28290 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 m sqlite3_result
282a0 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d _error() as UTF-
282b0 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 8. ^SQLite.** in
282c0 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 terprets the str
282d0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ing from sqlite3
282e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
282f0 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e ) as UTF-16 in n
28300 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 ative.** byte or
28310 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 der. ^If the th
28320 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
28330 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28340 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 error().** or sq
28350 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
28360 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 or16() is negati
28370 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 ve then SQLite t
28380 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f akes as the erro
28390 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c r.** message all
283a0 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 text up through
283b0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
283c0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 character..** ^I
283d0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
283e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
283f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
28400 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 or.** sqlite3_re
28410 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 sult_error16() i
28420 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 s non-negative t
28430 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
28440 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 that many.** by
28450 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 tes (not charact
28460 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e ers) from the 2n
28470 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 d parameter as t
28480 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
28490 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
284a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
284b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 and sqlite3_res
284c0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a ult_error16().**
284d0 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 routines make a
284e0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
284f0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
28500 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a ge text before.*
28510 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 * they return.
28520 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 Hence, the calli
28530 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 ng function can
28540 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a deallocate or.**
28550 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 modify the text
28560 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 after they retu
28570 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e rn without harm.
28580 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
28590 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f _result_error_co
285a0 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 de() function ch
285b0 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 anges the error
285c0 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 code.** returned
285d0 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 by SQLite as a
285e0 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 result of an err
285f0 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e or in a function
28600 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a . ^By default,.
28610 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 ** the error cod
28620 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f e is SQLITE_ERRO
28630 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e R. ^A subsequen
28640 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 t call to sqlite
28650 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
28660 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
28670 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
28680 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 resets the error
28690 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f code to SQLITE_
286a0 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ERROR..**.** ^Th
286b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
286c0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 _toobig() interf
286d0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
286e0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 e to throw an er
286f0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e ror.** indicatin
28700 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 g that a string
28710 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c or BLOB is too l
28720 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 ong to represent
28730 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
28740 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 ite3_result_nome
28750 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 m() interface ca
28760 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
28770 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a hrow an error.**
28780 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
28790 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
287a0 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a tion failed..**.
287b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
287c0 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 result_int() int
287d0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
287e0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
287f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
28800 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
28810 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 ion to be the 32
28820 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
28830 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 ger.** value giv
28840 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 en in the 2nd ar
28850 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 gument..** ^The
28860 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
28870 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 nt64() interface
28880 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
28890 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
288a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
288b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
288c0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 be the 64-bit s
288d0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
288e0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 value given in
288f0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 the 2nd argument
28900 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
28910 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
28920 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
28930 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
28940 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
28950 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
28960 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
28970 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
28980 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28990 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f text(), sqlite3_
289a0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c result_text16(),
289b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
289c0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 lt_text16le(), a
289d0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c nd sqlite3_resul
289e0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 t_text16be() int
289f0 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 erfaces.** set t
28a00 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
28a10 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
28a20 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
28a30 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 ion to be.** a t
28a40 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 ext string which
28a50 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 is represented
28a60 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 as UTF-8, UTF-16
28a70 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
28a80 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 er,.** UTF-16 li
28a90 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 ttle endian, or
28aa0 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 UTF-16 big endia
28ab0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e n, respectively.
28ac0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 .** ^SQLite take
28ad0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c s the text resul
28ae0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 t from the appli
28af0 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 cation from.** t
28b00 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
28b10 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
28b20 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
28b30 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 erfaces..** ^If
28b40 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
28b50 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
28b60 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
28b70 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e terfaces.** is n
28b80 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 egative, then SQ
28b90 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c Lite takes resul
28ba0 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 t text from the
28bb0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 2nd parameter.**
28bc0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 through the fir
28bd0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 st zero characte
28be0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 r..** ^If the 3r
28bf0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
28c00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
28c10 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
28c20 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 es.** is non-neg
28c30 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d ative, then as m
28c40 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 any bytes (not c
28c50 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 haracters) of th
28c60 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 e text.** pointe
28c70 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 d to by the 2nd
28c80 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 parameter are ta
28c90 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 ken as the appli
28ca0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a cation-defined.*
28cb0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c * function resul
28cc0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 t..** ^If the 4t
28cd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
28ce0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
28cf0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
28d00 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 es.** or sqlite3
28d10 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
28d20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
28d30 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
28d40 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 calls that.** fu
28d50 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 nction as the de
28d60 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 structor on the
28d70 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 text or BLOB res
28d80 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a ult when it has.
28d90 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e ** finished usin
28da0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a g that result..*
28db0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 * ^If the 4th pa
28dc0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
28dd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
28de0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f xt* interfaces o
28df0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
28e00 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
28e10 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
28e20 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ant SQLITE_STATI
28e30 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a C, then SQLite.*
28e40 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 * assumes that t
28e50 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
28e60 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e result is in con
28e70 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 stant space and
28e80 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 does not.** copy
28e90 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
28ea0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f the parameter no
28eb0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 r call a destruc
28ec0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 tor on the conte
28ed0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 nt.** when it ha
28ee0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 s finished using
28ef0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a that result..**
28f00 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
28f10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
28f20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
28f30 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
28f40 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
28f50 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
28f60 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
28f70 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
28f80 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 .** then SQLite
28f90 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
28fa0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 the result into
28fb0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 space obtained f
28fc0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c rom.** from [sql
28fd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 ite3_malloc()] b
28fe0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 efore it returns
28ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
29000 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
29010 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 e() interface se
29020 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 ts the result of
29030 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
29040 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
29050 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 tion to be a cop
29060 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 y the.** [unprot
29070 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
29080 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 lue] object spec
29090 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 ified by the 2nd
290a0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 parameter. ^Th
290b0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 e.** sqlite3_res
290c0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 ult_value() inte
290d0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f rface makes a co
290e0 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 py of the [sqlit
290f0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 e3_value].** so
29100 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 that the [sqlite
29110 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 3_value] specifi
29120 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 ed in the parame
29130 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f ter may change o
29140 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 r.** be dealloca
29150 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 ted after sqlite
29160 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
29170 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 returns without
29180 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 harm..** ^A [pr
29190 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
291a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 value] object ma
291b0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 y always be used
291c0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e where an.** [un
291d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
291e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
291f0 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 is required, so
29200 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f either.** kind o
29210 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 f [sqlite3_value
29220 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 ] object can be
29230 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 used with this i
29240 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
29250 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 If these routine
29260 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f s are called fro
29270 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 m within the dif
29280 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a ferent thread.**
29290 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f than the one co
292a0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 ntaining the app
292b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
292c0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 function that r
292d0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b eceived.** the [
292e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d sqlite3_context]
292f0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 pointer, the re
29300 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
29310 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c ned..*/.void sql
29320 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
29330 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29340 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
29350 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 int, void(*)(voi
29360 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 d*));.void sqlit
29370 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 e3_result_double
29380 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29390 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 *, double);.void
293a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
293b0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f error(sqlite3_co
293c0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
293d0 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 ar*, int);.void
293e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
293f0 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 rror16(sqlite3_c
29400 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
29410 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 oid*, int);.void
29420 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
29430 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c error_toobig(sql
29440 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
29450 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
29460 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 ult_error_nomem(
29470 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
29480 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
29490 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 result_error_cod
294a0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
294b0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 t*, int);.void s
294c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
294d0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
294e0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 t*, int);.void s
294f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
29500 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 t64(sqlite3_cont
29510 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ext*, sqlite3_in
29520 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 t64);.void sqlit
29530 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 e3_result_null(s
29540 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
29550 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
29560 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 esult_text(sqlit
29570 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
29580 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 st char*, int, v
29590 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
295a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
295b0 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 ult_text16(sqlit
295c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
295d0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
295e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
295f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
29600 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c ult_text16le(sql
29610 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
29620 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
29630 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
29640 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
29650 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 sult_text16be(sq
29660 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
29670 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
29680 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
29690 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
296a0 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 esult_value(sqli
296b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 te3_context*, sq
296c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 lite3_value*);.v
296d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
296e0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 lt_zeroblob(sqli
296f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
29700 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t n);../*.** CAP
29710 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 I3REF: Define Ne
29720 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 w Collating Sequ
29730 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ences.**.** Thes
29740 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 e functions are
29750 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 used to add new
29760 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
29770 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 ces to the.** [d
29780 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
29790 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 on] specified as
297a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
297b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ent..**.** ^The
297c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 name of the new
297d0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
297e0 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 ce is specified
297f0 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e as a UTF-8 strin
29800 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 g.** for sqlite3
29810 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
29820 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
29830 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
29840 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 _v2().** and a U
29850 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 TF-16 string for
29860 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
29870 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 5e collation16(). ^
29880 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 In all cases.**
29890 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 the name is pass
298a0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
298b0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
298c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 nt..**.** ^The t
298d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 hird argument ma
298e0 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 y be one of the
298f0 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 constants [SQLIT
29900 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c E_UTF8],.** [SQL
29910 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72 ITE_UTF16LE], or
29920 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
29930 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ], indicating th
29940 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 at the user-supp
29950 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 lied.** routine
29960 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 expects to be pa
29970 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f ssed pointers to
29980 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 strings encoded
29990 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a using UTF-8,.**
299a0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 UTF-16 little-e
299b0 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 ndian, or UTF-16
299c0 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 big-endian, res
299d0 70 65 63 74 69 76 65 6c 79 2e 20 5e 54 68 65 0a pectively. ^The.
299e0 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e ** third argumen
299f0 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 t might also be
29a00 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 [SQLITE_UTF16] t
29a10 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 o indicate that
29a20 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 the routine.** e
29a30 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 xpects pointers
29a40 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73 74 72 to be UTF-16 str
29a50 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69 ings in the nati
29a60 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f ve byte order, o
29a70 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e r the.** argumen
29a80 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 t can be [SQLITE
29a90 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 _UTF16_ALIGNED]
29aa0 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f if the.** the ro
29ab0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f utine expects po
29ac0 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 inters to 16-bit
29ad0 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 word aligned st
29ae0 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d rings.** of UTF-
29af0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
29b00 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a byte order..**.
29b10 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** A pointer to
29b20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 the user supplie
29b30 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 d routine must b
29b40 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
29b50 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e fifth.** argumen
29b60 74 2e 20 20 5e 49 66 20 69 74 20 69 73 20 4e 55 t. ^If it is NU
29b70 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 LL, this is the
29b80 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 same as deleting
29b90 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a the collation.*
29ba0 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 * sequence (so t
29bb0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f hat SQLite canno
29bc0 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 t call it anymor
29bd0 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 69 6d e)..** ^Each tim
29be0 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f e the applicatio
29bf0 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 n supplied funct
29c00 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 ion is invoked,
29c10 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 it is passed.**
29c20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72 as its first par
29c30 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 ameter a copy of
29c40 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 the void* passe
29c50 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 d as the fourth
29c60 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 argument.** to s
29c70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
29c80 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c llation() or sql
29c90 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
29ca0 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a ation16()..**.**
29cb0 20 5e 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 ^The remaining
29cc0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 arguments to the
29cd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 application-sup
29ce0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 plied routine ar
29cf0 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a e two strings,.*
29d00 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 * each represent
29d10 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c ed by a (length,
29d20 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 data) pair and
29d30 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 encoded in the e
29d40 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 ncoding.** that
29d50 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 was passed as th
29d60 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
29d70 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 when the collat
29d80 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 ion sequence was
29d90 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 .** registered.
29da0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
29db0 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 defined collati
29dc0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c on routine shoul
29dd0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 d.** return nega
29de0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f tive, zero or po
29df0 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69 sitive if the fi
29e00 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 rst string is le
29e10 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 ss than,.** equa
29e20 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 l to, or greater
29e30 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 than the second
29e40 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 string. i.e. (S
29e50 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 TRING1 - STRING2
29e60 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )..**.** ^The sq
29e70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
29e80 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b lation_v2() work
29e90 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 s like sqlite3_c
29ea0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
29eb0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 ).** except that
29ec0 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 it takes an ext
29ed0 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 ra argument whic
29ee0 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f h is a destructo
29ef0 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c r for.** the col
29f00 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 64 65 lation. ^The de
29f10 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c structor is call
29f20 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c ed when the coll
29f30 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 ation is.** dest
29f40 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 royed and is pas
29f50 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 sed a copy of th
29f60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
29f70 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 er void* pointer
29f80 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 .** of the sqlit
29f90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
29fa0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e 43 6f ion_v2()..** ^Co
29fb0 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 llations are des
29fc0 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 troyed when they
29fd0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 are overridden
29fe0 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 by later calls t
29ff0 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 o the.** collati
2a000 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 on creation func
2a010 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 tions or when th
2a020 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2a030 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 ection] is close
2a040 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 d.** using [sqli
2a050 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a te3_close()]..**
2a060 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b .** See also: [
2a070 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
2a080 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 n_needed()] and
2a090 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 [sqlite3_collati
2a0a0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a on_needed16()]..
2a0b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
2a0c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
2a0d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
2a0e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
2a0f0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 e, . int eTextR
2a100 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 ep, . void*,.
2a110 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 int(*xCompare)(v
2a120 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
2a130 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
2a140 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c oid*).);.int sql
2a150 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
2a160 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 ation_v2(. sqli
2a170 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 te3*, . const c
2a180 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 har *zName, . i
2a190 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
2a1a0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 void*,. int(*xC
2a1b0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
2a1c0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
2a1d0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a t,const void*),.
2a1e0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 void(*xDestroy
2a1f0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 )(void*).);.int
2a200 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
2a210 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 ollation16(. sq
2a220 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 lite3*, . const
2a230 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 void *zName,.
2a240 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 int eTextRep, .
2a250 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 void*,. int(*x
2a260 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 Compare)(void*,i
2a270 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 nt,const void*,i
2a280 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a nt,const void*).
2a290 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2a2a0 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 EF: Collation Ne
2a2b0 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a eded Callbacks.*
2a2c0 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 *.** ^To avoid h
2a2d0 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 aving to registe
2a2e0 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 r all collation
2a2f0 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 sequences before
2a300 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 a database.** c
2a310 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 an be used, a si
2a320 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ngle callback fu
2a330 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 nction may be re
2a340 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 gistered with th
2a350 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
2a360 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 onnection] to be
2a370 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
2a380 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 r an undefined c
2a390 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 ollation.** sequ
2a3a0 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 ence is required
2a3b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2a3c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 function is regi
2a3d0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 stered using the
2a3e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
2a3f0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c on_needed() API,
2a400 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 .** then it is p
2a410 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 assed the names
2a420 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c of undefined col
2a430 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 lation sequences
2a440 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 as strings.** e
2a450 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e ncoded in UTF-8.
2a460 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c ^If sqlite3_col
2a470 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
2a480 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 ) is used,.** th
2a490 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 e names are pass
2a4a0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 ed as UTF-16 in
2a4b0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 machine native b
2a4c0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 yte order..** ^A
2a4d0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 call to either
2a4e0 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 function replace
2a4f0 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 s the existing c
2a500 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 ollation-needed
2a510 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
2a520 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 ^(When the callb
2a530 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 ack is invoked,
2a540 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
2a550 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 nt passed is a c
2a560 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 opy.** of the se
2a570 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
2a580 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
2a590 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a on_needed() or.*
2a5a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 * sqlite3_collat
2a5b0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 ion_needed16().
2a5c0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
2a5d0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 ment is the data
2a5e0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
2a5f0 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 on. The third a
2a600 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f rgument is one o
2a610 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c f [SQLITE_UTF8],
2a620 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
2a630 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 ],.** or [SQLITE
2a640 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 _UTF16LE], indic
2a650 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 ating the most d
2a660 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 esirable form of
2a670 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a the collation.*
2a680 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 * sequence funct
2a690 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 ion required. T
2a6a0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2a6b0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ter is the name
2a6c0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 of the.** requir
2a6d0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ed collation seq
2a6e0 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 uence.)^.**.** T
2a6f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
2a700 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 tion should regi
2a710 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 ster the desired
2a720 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 collation using
2a730 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
2a740 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d ate_collation()]
2a750 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 , [sqlite3_creat
2a760 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d e_collation16()]
2a770 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
2a780 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
2a790 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 n_v2()]..*/.int
2a7a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
2a7b0 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 n_needed(. sqli
2a7c0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 te3*, . void*,
2a7d0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a . void(*)(void*
2a7e0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 ,sqlite3*,int eT
2a7f0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 extRep,const cha
2a800 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 r*).);.int sqlit
2a810 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
2a820 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 ded16(. sqlite3
2a830 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 *, . void*,. v
2a840 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
2a850 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 ite3*,int eTextR
2a860 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a ep,const void*).
2a870 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 );../*.** Specif
2a880 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e y the key for an
2a890 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 encrypted datab
2a8a0 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 ase. This routi
2a8b0 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 ne should be.**
2a8c0 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 called right aft
2a8d0 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 er sqlite3_open(
2a8e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 )..**.** The cod
2a8f0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 e to implement t
2a900 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 his API is not a
2a910 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 vailable in the
2a920 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a public release.*
2a930 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a * of SQLite..*/.
2a940 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 int sqlite3_key(
2a950 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2a960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2a970 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f /* Database to
2a980 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 be rekeyed */.
2a990 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 const void *pKe
2a9a0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 y, int nKey
2a9b0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b /* The key */.);
2a9c0 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 ../*.** Change t
2a9d0 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 he key on an ope
2a9e0 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 n database. If
2a9f0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 the current data
2aa00 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 base is not.** e
2aa10 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 ncrypted, this r
2aa20 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 outine will encr
2aa30 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 ypt it. If pNew
2aa40 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 ==0 or nNew==0,
2aa50 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
2aa60 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a is decrypted..**
2aa70 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 .** The code to
2aa80 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 implement this A
2aa90 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 PI is not availa
2aaa0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 ble in the publi
2aab0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 c release.** of
2aac0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 SQLite..*/.int s
2aad0 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 qlite3_rekey(.
2aae0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
2aaf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2ab00 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 * Database to be
2ab10 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f rekeyed */. co
2ab20 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 nst void *pKey,
2ab30 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 int nKey /*
2ab40 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 The new key */.)
2ab50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2ab60 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 F: Suspend Execu
2ab70 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 tion For A Short
2ab80 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 Time.**.** ^The
2ab90 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 sqlite3_sleep()
2aba0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 function causes
2abb0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 the current thr
2abc0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 ead to suspend e
2abd0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 xecution.** for
2abe0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 at least a numbe
2abf0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
2ac00 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 s specified in i
2ac10 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ts parameter..**
2ac20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 65 72 .** ^If the oper
2ac30 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 ating system doe
2ac40 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c s not support sl
2ac50 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 eep requests wit
2ac60 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 h.** millisecond
2ac70 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e time resolution
2ac80 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 , then the time
2ac90 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 will be rounded
2aca0 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 up to.** the nea
2acb0 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 5e 54 68 rest second. ^Th
2acc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c e number of mill
2acd0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
2ace0 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 p actually.** re
2acf0 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 quested from the
2ad00 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
2ad10 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a m is returned..*
2ad20 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 *.** ^SQLite imp
2ad30 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 lements this int
2ad40 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e erface by callin
2ad50 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a g the xSleep().*
2ad60 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 * method of the
2ad70 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
2ad80 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f _vfs] object..*/
2ad90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 .int sqlite3_sle
2ada0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ep(int);../*.**
2adb0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f CAPI3REF: Name O
2adc0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c f The Folder Hol
2add0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 ding Temporary F
2ade0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 iles.**.** ^If t
2adf0 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 his global varia
2ae00 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 ble is made to p
2ae10 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 oint to a string
2ae20 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 which is.** the
2ae30 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 name of a folde
2ae40 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 r (a.k.a. direct
2ae50 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 ory), then all t
2ae60 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a emporary files.*
2ae70 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c * created by SQL
2ae80 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 ite when using a
2ae90 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 built-in [sqlit
2aea0 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a e3_vfs | VFS].**
2aeb0 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 will be placed
2aec0 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 in that director
2aed0 79 2e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 y. ^If this var
2aee0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 iable.** is a NU
2aef0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
2af00 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 SQLite performs
2af10 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e a search for an
2af20 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 appropriate.**
2af30 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 temporary file d
2af40 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 irectory..**.**
2af50 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 It is not safe t
2af60 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 o read or modify
2af70 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 this variable i
2af80 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a n more than one.
2af90 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 ** thread at a t
2afa0 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 ime. It is not
2afb0 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 safe to read or
2afc0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 modify this vari
2afd0 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 able.** if a [da
2afe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2aff0 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 n] is being used
2b000 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
2b010 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a e in a separate.
2b020 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 ** thread..** It
2b030 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 is intended tha
2b040 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 t this variable
2b050 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 be set once.** a
2b060 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 s part of proces
2b070 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
2b080 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 and before any
2b090 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
2b0a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 .** routines hav
2b0b0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e e been called an
2b0c0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 d that this vari
2b0d0 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 able remain unch
2b0e0 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 anged.** thereaf
2b0f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
2b100 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
2b110 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 ctory pragma] ma
2b120 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 y modify this va
2b130 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 riable and cause
2b140 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 .** it to point
2b150 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
2b160 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
2b170 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 _malloc]. ^Furt
2b180 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 hermore,.** the
2b190 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
2b1a0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c ctory pragma] al
2b1b0 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 ways assumes tha
2b1c0 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 t any string.**
2b1d0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
2b1e0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 le points to is
2b1f0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f held in memory o
2b200 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a btained from .**
2b210 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
2b220 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 ] and the pragma
2b230 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 may attempt to
2b240 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 free that memory
2b250 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
2b260 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e e3_free]..** Hen
2b270 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 ce, if this vari
2b280 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 able is modified
2b290 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 directly, eithe
2b2a0 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a r it should be.*
2b2b0 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d * made NULL or m
2b2c0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
2b2d0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
2b2e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
2b2f0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 lloc].** or else
2b300 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 the use of the
2b310 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
2b320 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 ctory pragma] sh
2b330 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e ould be avoided.
2b340 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 .*/.SQLITE_EXTER
2b350 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f N char *sqlite3_
2b360 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a temp_directory;.
2b370 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2b380 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 Test For Auto-C
2b390 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 ommit Mode.** KE
2b3a0 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d YWORDS: {autocom
2b3b0 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 mit mode}.**.**
2b3c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
2b3d0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e _autocommit() in
2b3e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2b3f0 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a non-zero or.** z
2b400 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e ero if the given
2b410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2b420 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f tion is or is no
2b430 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 t in autocommit
2b440 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 mode,.** respect
2b450 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d ively. ^Autocom
2b460 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 mit mode is on b
2b470 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 y default..** ^A
2b480 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 utocommit mode i
2b490 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 s disabled by a
2b4a0 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e [BEGIN] statemen
2b4b0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 t..** ^Autocommi
2b4c0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 t mode is re-ena
2b4d0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 bled by a [COMMI
2b4e0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d T] or [ROLLBACK]
2b4f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 ..**.** If certa
2b500 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f in kinds of erro
2b510 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 rs occur on a st
2b520 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 atement within a
2b530 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 multi-statement
2b540 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 .** transaction
2b550 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e (errors includin
2b560 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c g [SQLITE_FULL],
2b570 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c [SQLITE_IOERR],
2b580 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
2b590 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 M], [SQLITE_BUSY
2b5a0 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 ], and [SQLITE_I
2b5b0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 NTERRUPT]) then
2b5c0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 the.** transacti
2b5d0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c on might be roll
2b5e0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
2b5f0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 cally. The only
2b600 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 way to.** find
2b610 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 out whether SQLi
2b620 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 te automatically
2b630 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 rolled back the
2b640 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 transaction aft
2b650 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 er.** an error i
2b660 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 s to use this fu
2b670 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 nction..**.** If
2b680 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
2b690 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f changes the auto
2b6a0 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 commit status of
2b6b0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
2b6c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
2b6d0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 e this routine i
2b6e0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 s running, then
2b6f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
2b700 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 .** is undefined
2b710 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2b720 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 _get_autocommit(
2b730 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
2b740 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 * CAPI3REF: Find
2b750 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 The Database Ha
2b760 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 ndle Of A Prepar
2b770 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a ed Statement.**.
2b780 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2b790 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 db_handle interf
2b7a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
2b7b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2b7c0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 tion] handle.**
2b7d0 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 to which a [prep
2b7e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2b7f0 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b belongs. ^The [
2b800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2b810 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ion].** returned
2b820 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 by sqlite3_db_h
2b830 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d andle is the sam
2b840 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2b850 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 ection].** that
2b860 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 was the first ar
2b870 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 gument.** to the
2b880 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2b890 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 e_v2()] call (or
2b8a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 its variants) t
2b8b0 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a hat was used to.
2b8c0 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 ** create the st
2b8d0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 atement in the f
2b8e0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 irst place..*/.s
2b8f0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f qlite3 *sqlite3_
2b900 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 db_handle(sqlite
2b910 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
2b920 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 CAPI3REF: Find
2b930 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 the next prepare
2b940 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a d statement.**.*
2b950 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 * ^This interfac
2b960 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
2b970 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 ter to the next
2b980 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2b990 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 ent] after.** pS
2b9a0 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 tmt associated w
2b9b0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
2b9c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 e connection] pD
2b9d0 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 b. ^If pStmt is
2b9e0 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 NULL.** then th
2b9f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 is interface ret
2ba00 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2ba10 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 o the first prep
2ba20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
2ba30 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
2ba40 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 h the database c
2ba50 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 onnection pDb.
2ba60 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 ^If no prepared
2ba70 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 statement.** sat
2ba80 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 isfies the condi
2ba90 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f tions of this ro
2baa0 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e utine, it return
2bab0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 s NULL..**.** Th
2bac0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2bad0 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 ection] pointer
2bae0 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a D in a call to.*
2baf0 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f * [sqlite3_next_
2bb00 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 stmt(D,S)] must
2bb10 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e refer to an open
2bb20 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
2bb30 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 nection and in p
2bb40 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e articular must n
2bb50 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ot be a NULL poi
2bb60 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 nter..*/.sqlite3
2bb70 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e _stmt *sqlite3_n
2bb80 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 ext_stmt(sqlite3
2bb90 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 *pDb, sqlite3_s
2bba0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
2bbb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
2bbc0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 mmit And Rollbac
2bbd0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 k Notification C
2bbe0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e allbacks.**.** ^
2bbf0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d The sqlite3_comm
2bc00 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 it_hook() interf
2bc10 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
2bc20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 callback.** func
2bc30 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b tion to be invok
2bc40 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 ed whenever a tr
2bc50 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f ansaction is [CO
2bc60 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 MMIT | committed
2bc70 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 ]..** ^Any callb
2bc80 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 ack set by a pre
2bc90 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 vious call to sq
2bca0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
2bcb0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 k().** for the s
2bcc0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
2bcd0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 nection is overr
2bce0 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 idden..** ^The s
2bcf0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f qlite3_rollback_
2bd00 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 hook() interface
2bd10 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
2bd20 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f lback.** functio
2bd30 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 n to be invoked
2bd40 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 whenever a trans
2bd50 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 action is [ROLLB
2bd60 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 ACK | rolled bac
2bd70 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c k]..** ^Any call
2bd80 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 back set by a pr
2bd90 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 evious call to s
2bda0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f qlite3_rollback_
2bdb0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 hook().** for th
2bdc0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
2bdd0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 connection is ov
2bde0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 erridden..** ^Th
2bdf0 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 e pArg argument
2be00 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 is passed throug
2be10 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 h to the callbac
2be20 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 k..** ^If the ca
2be30 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d llback on a comm
2be40 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e it hook function
2be50 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
2be60 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 o,.** then the c
2be70 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 ommit is convert
2be80 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 ed into a rollba
2be90 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ck..**.** ^The s
2bea0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
2beb0 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 ok(D,C,P) and sq
2bec0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
2bed0 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 ook(D,C,P) funct
2bee0 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 ions.** return t
2bef0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 he P argument fr
2bf00 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 om the previous
2bf10 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 call of the same
2bf20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 function.** on
2bf30 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
2bf40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
2bf50 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a , or NULL for.**
2bf60 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 the first call
2bf70 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f for each functio
2bf80 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 n on D..**.** Th
2bf90 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 e callback imple
2bfa0 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e mentation must n
2bfb0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
2bfc0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
2bfd0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
2bfe0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
2bff0 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c invoked the call
2c000 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f back. Any actio
2c010 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 ns.** to modify
2c020 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2c030 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 nection must be
2c040 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 deferred until a
2c050 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 fter the.** comp
2c060 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 letion of the [s
2c070 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 qlite3_step()] c
2c080 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
2c090 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a ed the commit.**
2c0a0 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f or rollback hoo
2c0b0 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 k in the first p
2c0c0 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 lace..** Note th
2c0d0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
2c0e0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
2c0f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
2c100 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
2c110 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
2c120 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
2c130 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
2c140 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
2c150 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 agraph..**.** ^R
2c160 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c egistering a NUL
2c170 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 L function disab
2c180 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b les the callback
2c190 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 ..**.** ^When th
2c1a0 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 e commit hook ca
2c1b0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 llback routine r
2c1c0 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 eturns zero, the
2c1d0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 [COMMIT].** ope
2c1e0 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 ration is allowe
2c1f0 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f d to continue no
2c200 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 rmally. ^If the
2c210 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 commit hook.**
2c220 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
2c230 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d , then the [COMM
2c240 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 IT] is converted
2c250 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 into a [ROLLBAC
2c260 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c K]..** ^The roll
2c270 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 back hook is inv
2c280 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 oked on a rollba
2c290 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 ck that results
2c2a0 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a from a commit.**
2c2b0 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 hook returning
2c2c0 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 non-zero, just a
2c2d0 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 s it would be wi
2c2e0 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c th any other rol
2c2f0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f lback..**.** ^Fo
2c300 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f r the purposes o
2c310 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 f this API, a tr
2c320 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 ansaction is sai
2c330 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a d to have been.*
2c340 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 * rolled back if
2c350 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f an explicit "RO
2c360 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e LLBACK" statemen
2c370 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f t is executed, o
2c380 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 r.** an error or
2c390 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 constraint caus
2c3a0 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 es an implicit r
2c3b0 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 ollback to occur
2c3c0 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 ..** ^The rollba
2c3d0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e ck callback is n
2c3e0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 ot invoked if a
2c3f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a transaction is.*
2c400 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
2c410 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 rolled back beca
2c420 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 use the database
2c430 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
2c440 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 losed..** ^The r
2c450 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b ollback callback
2c460 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 is not invoked
2c470 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e if a transaction
2c480 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 is.** rolled ba
2c490 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d ck because a com
2c4a0 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 mit callback ret
2c4b0 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a urned non-zero..
2c4c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 **.** See also t
2c4d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 he [sqlite3_upda
2c4e0 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 te_hook()] inter
2c4f0 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 face..*/.void *s
2c500 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
2c510 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ok(sqlite3*, int
2c520 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 (*)(void*), void
2c530 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 *);.void *sqlite
2c540 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
2c550 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a sqlite3*, void(*
2c560 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a )(void *), void*
2c570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2c580 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 EF: Data Change
2c590 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c Notification Cal
2c5a0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 lbacks.**.** ^Th
2c5b0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 e sqlite3_update
2c5c0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 _hook() interfac
2c5d0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 e registers a ca
2c5e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a llback function.
2c5f0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ** with the [dat
2c600 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2c610 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 ] identified by
2c620 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
2c630 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f nt.** to be invo
2c640 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 ked whenever a r
2c650 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 ow is updated, i
2c660 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
2c670 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c ed..** ^Any call
2c680 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 back set by a pr
2c690 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 evious call to t
2c6a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 his function.**
2c6b0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 for the same dat
2c6c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2c6d0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a is overridden..
2c6e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e **.** ^The secon
2c6f0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 d argument is a
2c700 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 pointer to the f
2c710 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b unction to invok
2c720 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 e when a.** row
2c730 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 is updated, inse
2c740 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e rted or deleted.
2c750 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
2c760 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 rgument to the c
2c770 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 allback is a cop
2c780 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 y of the third a
2c790 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 rgument.** to sq
2c7a0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
2c7b0 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 k()..** ^The sec
2c7c0 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 ond callback arg
2c7d0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 ument is one of
2c7e0 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c [SQLITE_INSERT],
2c7f0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d [SQLITE_DELETE]
2c800 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
2c810 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 UPDATE], dependi
2c820 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 ng on the operat
2c830 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 ion that caused
2c840 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 the callback.**
2c850 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a to be invoked..*
2c860 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 * ^The third and
2c870 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
2c880 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 s to the callbac
2c890 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 k contain pointe
2c8a0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 rs to the.** dat
2c8b0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 abase and table
2c8c0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 name containing
2c8d0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 the affected row
2c8e0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 ..** ^The final
2c8f0 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 callback paramet
2c900 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 er is the [rowid
2c910 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a ] of the row..**
2c920 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 ^In the case of
2c930 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 an update, this
2c940 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 is the [rowid]
2c950 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 after the update
2c960 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a takes place..**
2c970 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 .** ^(The update
2c980 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 hook is not inv
2c990 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e oked when intern
2c9a0 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 al system tables
2c9b0 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 are.** modified
2c9c0 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 (i.e. sqlite_ma
2c9d0 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f ster and sqlite_
2c9e0 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a sequence).)^.**.
2c9f0 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 ** ^In the curre
2ca00 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f nt implementatio
2ca10 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f n, the update ho
2ca20 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 ok.** is not inv
2ca30 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 oked when duplic
2ca40 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 ation rows are d
2ca50 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f eleted because o
2ca60 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 f an.** [ON CONF
2ca70 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 LICT | ON CONFLI
2ca80 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 CT REPLACE] clau
2ca90 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 se. ^Nor is the
2caa0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 update hook.**
2cab0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 invoked when row
2cac0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 s are deleted us
2cad0 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 ing the [truncat
2cae0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e e optimization].
2caf0 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f .** The exceptio
2cb00 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 ns defined in th
2cb10 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 is paragraph mig
2cb20 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 ht change in a f
2cb30 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 uture.** release
2cb40 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
2cb50 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f * The update hoo
2cb60 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e k implementation
2cb70 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
2cb80 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
2cb90 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
2cba0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2cbb0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
2cbc0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 he update hook.
2cbd0 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 Any actions.**
2cbe0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 to modify the da
2cbf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2cc00 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 n must be deferr
2cc10 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 ed until after t
2cc20 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e he.** completion
2cc30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
2cc40 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 _step()] call th
2cc50 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 at triggered the
2cc60 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a update hook..**
2cc70 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
2cc80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2cc90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
2cca0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
2ccb0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
2ccc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
2ccd0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
2cce0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
2ccf0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
2cd00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2cd10 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 e3_update_hook(D
2cd20 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a ,C,P) function.*
2cd30 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 * returns the P
2cd40 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 argument from th
2cd50 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a e previous call.
2cd60 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b ** on the same [
2cd70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2cd80 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 ion] D, or NULL
2cd90 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 for.** the first
2cda0 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a call on D..**.*
2cdb0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b * See also the [
2cdc0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
2cdd0 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ook()] and [sqli
2cde0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f te3_rollback_hoo
2cdf0 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 k()].** interfac
2ce00 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c es..*/.void *sql
2ce10 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
2ce20 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
2ce30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c void(*)(void *,
2ce40 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 int ,char const
2ce50 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 *,char const *,s
2ce60 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 qlite3_int64),.
2ce70 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a void*.);../*.**
2ce80 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c CAPI3REF: Enabl
2ce90 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 e Or Disable Sha
2cea0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a red Pager Cache.
2ceb0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 ** KEYWORDS: {sh
2cec0 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a ared cache}.**.*
2ced0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 * ^(This routine
2cee0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
2cef0 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 bles the sharing
2cf00 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2cf10 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 cache.** and sc
2cf20 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 hema data struct
2cf30 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 ures between [da
2cf40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2cf50 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d n | connections]
2cf60 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 .** to the same
2cf70 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e database. Sharin
2cf80 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 g is enabled if
2cf90 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 the argument is
2cfa0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 true.** and disa
2cfb0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 bled if the argu
2cfc0 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e ment is false.)^
2cfd0 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 .**.** ^Cache sh
2cfe0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 aring is enabled
2cff0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f and disabled fo
2d000 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 r an entire proc
2d010 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ess..** This is
2d020 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 a change as of S
2d030 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
2d040 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 5.0. In prior ve
2d050 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
2d060 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 ,.** sharing was
2d070 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
2d080 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 bled for each th
2d090 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e read separately.
2d0a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 .**.** ^(The cac
2d0b0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 he sharing mode
2d0c0 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 set by this inte
2d0d0 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c rface effects al
2d0e0 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 l subsequent.**
2d0f0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
2d100 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
2d110 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
2d120 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 and [sqlite3_ope
2d130 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 n16()]..** Exist
2d140 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e ing database con
2d150 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 nections continu
2d160 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e e use the sharin
2d170 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 g mode.** that w
2d180 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 as in effect at
2d190 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 the time they we
2d1a0 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a re opened.)^.**.
2d1b0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e ** ^(This routin
2d1c0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
2d1d0 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 E_OK] if shared
2d1e0 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 cache was enable
2d1f0 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a d or disabled.**
2d200 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 successfully.
2d210 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 An [error code]
2d220 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 is returned othe
2d230 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e rwise.)^.**.** ^
2d240 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 Shared cache is
2d250 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
2d260 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 ult. But this mi
2d270 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a ght change in.**
2d280 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
2d290 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 of SQLite. App
2d2a0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 lications that c
2d2b0 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 are about shared
2d2c0 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e .** cache settin
2d2d0 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 g should set it
2d2e0 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a explicitly..**.*
2d2f0 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 * See Also: [SQ
2d300 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 Lite Shared-Cach
2d310 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 e Mode].*/.int s
2d320 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 qlite3_enable_sh
2d330 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b ared_cache(int);
2d340 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2d350 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 : Attempt To Fre
2d360 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a e Heap Memory.**
2d370 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2d380 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
2d390 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
2d3a0 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 mpts to free N b
2d3b0 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 ytes.** of heap
2d3c0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f memory by deallo
2d3d0 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e cating non-essen
2d3e0 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f tial memory allo
2d3f0 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 cations.** held
2d400 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 by the database
2d410 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 library. Memor
2d420 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 y used to cache
2d430 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 database.** page
2d440 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 s to improve per
2d450 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 formance is an e
2d460 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 xample of non-es
2d470 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a sential memory..
2d480 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 ** ^sqlite3_rele
2d490 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 ase_memory() ret
2d4a0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2d4b0 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c of bytes actuall
2d4c0 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 y freed,.** whic
2d4d0 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 h might be more
2d4e0 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 or less than the
2d4f0 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 amount requeste
2d500 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
2d510 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
2d520 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
2d530 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 PI3REF: Impose A
2d540 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 Limit On Heap S
2d550 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ize.**.** ^The s
2d560 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
2d570 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 _limit() interfa
2d580 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 ce places a "sof
2d590 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 t" limit.** on t
2d5a0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 he amount of hea
2d5b0 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 p memory that ma
2d5c0 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 y be allocated b
2d5d0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 y SQLite..** ^If
2d5e0 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c an internal all
2d5f0 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 ocation is reque
2d600 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 sted that would
2d610 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f exceed the.** so
2d620 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b ft heap limit, [
2d630 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
2d640 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 memory()] is inv
2d650 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d oked one or.** m
2d660 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 ore times to fre
2d670 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 e up some space
2d680 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 before the alloc
2d690 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d ation is perform
2d6a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c ed..**.** ^The l
2d6b0 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 imit is called "
2d6c0 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66 soft" because if
2d6d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 [sqlite3_releas
2d6e0 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 e_memory()].** c
2d6f0 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 annot free suffi
2d700 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 cient memory to
2d710 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 prevent the limi
2d720 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 t from being exc
2d730 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 eeded,.** the me
2d740 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 mory is allocate
2d750 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 d anyway and the
2d760 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 current operati
2d770 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a on proceeds..**.
2d780 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f ** ^A negative o
2d790 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 r zero value for
2d7a0 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 N means that th
2d7b0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 ere is no soft h
2d7c0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a eap limit and.**
2d7d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 [sqlite3_releas
2d7e0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c e_memory()] will
2d7f0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
2d800 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 when memory is e
2d810 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 xhausted..** ^Th
2d820 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 e default value
2d830 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 for the soft hea
2d840 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e p limit is zero.
2d850 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 .**.** ^(SQLite
2d860 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 makes a best eff
2d870 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 ort to honor the
2d880 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
2d890 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 ..** But if the
2d8a0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
2d8b0 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 cannot be honore
2d8c0 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c d, execution wil
2d8d0 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 l.** continue wi
2d8e0 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e thout error or n
2d8f0 6f 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 otification.)^
2d900 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 This is why the
2d910 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c limit is.** call
2d920 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 ed a "soft" limi
2d930 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f t. It is adviso
2d940 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 ry only..**.** P
2d950 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 rior to SQLite v
2d960 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 ersion 3.5.0, th
2d970 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 is routine only
2d980 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 constrained the
2d990 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
2d9a0 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 ted by a single
2d9b0 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d thread - the sam
2d9c0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
2d9d0 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a h this routine.*
2d9e0 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 * runs. Beginni
2d9f0 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 ng with SQLite v
2da00 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 ersion 3.5.0, th
2da10 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
2da20 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 t is.** applied
2da30 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 to all threads.
2da40 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 The value specif
2da50 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 ied for the soft
2da60 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 heap limit.** i
2da70 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 s an upper bound
2da80 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 on the total me
2da90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
2daa0 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e for all threads.
2dab0 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 In.** version 3
2dac0 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f .5.0 there is no
2dad0 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c mechanism for l
2dae0 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 imiting the heap
2daf0 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e usage for.** in
2db00 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 dividual threads
2db10 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
2db20 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
2db30 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t(int);../*.** C
2db40 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 API3REF: Extract
2db50 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 Metadata About
2db60 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 A Column Of A Ta
2db70 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ble.**.** ^This
2db80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
2db90 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 metadata about a
2dba0 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e specific column
2dbb0 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a of a specific.*
2dbc0 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 * database table
2dbd0 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e accessible usin
2dbe0 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 g the [database
2dbf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
2dc00 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 le.** passed as
2dc10 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 the first functi
2dc20 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a on argument..**.
2dc30 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 ** ^The column i
2dc40 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 s identified by
2dc50 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 the second, thir
2dc60 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 d and fourth par
2dc70 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 ameters to.** th
2dc80 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 is function. ^Th
2dc90 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
2dca0 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 er is either the
2dcb0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
2dcc0 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 abase.** (i.e. "
2dcd0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f main", "temp", o
2dce0 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 r an attached da
2dcf0 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 tabase) containi
2dd00 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 ng the specified
2dd10 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c .** table or NUL
2dd20 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c L. ^If it is NUL
2dd30 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 L, then all atta
2dd40 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 ched databases a
2dd50 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 re searched.** f
2dd60 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 or the table usi
2dd70 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f ng the same algo
2dd80 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 rithm used by th
2dd90 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e e database engin
2dda0 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 e to.** resolve
2ddb0 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c unqualified tabl
2ddc0 65 20 72 65 66 65 72 65 6e 63 65 73 2e 29 5e 0a e references.)^.
2ddd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 **.** ^The third
2dde0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 and fourth para
2ddf0 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 meters to this f
2de00 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 unction are the
2de10 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e table and column
2de20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 .** name of the
2de30 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 desired column,
2de40 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 respectively. Ne
2de50 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 ither of these p
2de60 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 arameters.** may
2de70 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
2de80 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74 ^Metadata is ret
2de90 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 urned by writing
2dea0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c to the memory l
2deb0 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 ocations passed
2dec0 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e as the 5th.** an
2ded0 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 d subsequent par
2dee0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 ameters to this
2def0 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f function. ^Any o
2df00 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 f these argument
2df10 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c s may be.** NULL
2df20 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 , in which case
2df30 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
2df40 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 g element of met
2df50 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 adata is omitted
2df60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b ..**.** ^(<block
2df70 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 quote>.** <table
2df80 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 border="1">.**
2df90 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 <tr><th> Paramet
2dfa0 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 er <th> Output<b
2dfb0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 r>Type <th> Des
2dfc0 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c cription.**.** <
2dfd0 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e tr><td> 5th <td>
2dfe0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 const char* <td
2dff0 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c > Data type.** <
2e000 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e tr><td> 6th <td>
2e010 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 const char* <td
2e020 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c > Name of defaul
2e030 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 t collation sequ
2e040 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ence.** <tr><td>
2e050 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 7th <td> int
2e060 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 <td> True
2e070 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 if column has a
2e080 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 NOT NULL constra
2e090 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 int.** <tr><td>
2e0a0 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 8th <td> int
2e0b0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 <td> True i
2e0c0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 f column is part
2e0d0 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 of the PRIMARY
2e0e0 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 KEY.** <tr><td>
2e0f0 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 9th <td> int
2e100 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 <td> True i
2e110 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 f column is [AUT
2e120 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c OINCREMENT].** <
2e130 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f /table>.** </blo
2e140 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
2e150 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 ^The memory poi
2e160 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 nted to by the c
2e170 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 haracter pointer
2e180 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 s returned for t
2e190 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f he.** declaratio
2e1a0 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 n type and colla
2e1b0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 tion sequence is
2e1c0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 valid only unti
2e1d0 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 l the next.** ca
2e1e0 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 ll to any SQLite
2e1f0 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a API function..*
2e200 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 *.** ^If the spe
2e210 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 cified table is
2e220 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c actually a view,
2e230 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
2e240 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
2e250 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 .** ^If the spec
2e260 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 ified column is
2e270 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f "rowid", "oid" o
2e280 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 r "_rowid_" and
2e290 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 an.** [INTEGER P
2e2a0 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 RIMARY KEY] colu
2e2b0 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c mn has been expl
2e2c0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c icitly declared,
2e2d0 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 then the output
2e2e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 .** parameters a
2e2f0 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 re set for the e
2e300 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
2e310 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 ed column. ^(If
2e320 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 there is no.** e
2e330 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
2e340 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d ed [INTEGER PRIM
2e350 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c ARY KEY] column,
2e360 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 then the output
2e370 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 .** parameters a
2e380 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 re set as follow
2e390 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a s:.**.** <pre>.*
2e3a0 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a * data type:
2e3b0 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 "INTEGER".**
2e3c0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 collation sequ
2e3d0 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a ence: "BINARY".*
2e3e0 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 * not null:
2e3f0 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 0.** primary
2e400 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 key: 1.** a
2e410 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 uto increment: 0
2e420 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a .** </pre>)^.**.
2e430 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 ** ^(This functi
2e440 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 on may load one
2e450 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 or more schemas
2e460 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 from database fi
2e470 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 les. If an.** er
2e480 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e ror occurs durin
2e490 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 g this process,
2e4a0 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73 or if the reques
2e4b0 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c ted table or col
2e4c0 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 umn.** cannot be
2e4d0 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f found, an [erro
2e4e0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
2e4f0 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 ned and an error
2e500 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a message left.**
2e510 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 in the [databas
2e520 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 e connection] (t
2e530 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 o be retrieved u
2e540 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 sing sqlite3_err
2e550 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 msg()).)^.**.**
2e560 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c ^This API is onl
2e570 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 y available if t
2e580 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 he library was c
2e590 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
2e5a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
2e5b0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 LE_COLUMN_METADA
2e5c0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 TA] C-preprocess
2e5d0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 or symbol define
2e5e0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
2e5f0 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 3_table_column_m
2e600 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 etadata(. sqlit
2e610 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2e620 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 /* Connec
2e630 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 tion handle */.
2e640 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
2e650 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 Name, /*
2e660 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 Database name or
2e670 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 NULL */. const
2e680 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d char *zTableNam
2e690 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 e, /* Table
2e6a0 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 name */. const
2e6b0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d char *zColumnNam
2e6c0 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 e, /* Column
2e6d0 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 name */. char c
2e6e0 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 onst **pzDataTyp
2e6f0 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a e, /* OUTPUT:
2e700 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 Declared data t
2e710 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f ype */. char co
2e720 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c nst **pzCollSeq,
2e730 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 /* OUTPUT:
2e740 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e Collation sequen
2e750 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 ce name */. int
2e760 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 *pNotNull,
2e770 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 /* OUTP
2e780 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 UT: True if NOT
2e790 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 NULL constraint
2e7a0 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 exists */. int
2e7b0 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 *pPrimaryKey,
2e7c0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 /* OUTPU
2e7d0 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d T: True if colum
2e7e0 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a n part of PK */.
2e7f0 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 int *pAutoinc
2e800 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2e810 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 OUTPUT: True if
2e820 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d column is auto-
2e830 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a increment */.);.
2e840 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2e850 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 Load An Extensi
2e860 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 on.**.** ^This i
2e870 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 nterface loads a
2e880 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 n SQLite extensi
2e890 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 on library from
2e8a0 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a the named file..
2e8b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2e8c0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f e3_load_extensio
2e8d0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 n() interface at
2e8e0 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 tempts to load a
2e8f0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65 n.** SQLite exte
2e900 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f nsion library co
2e910 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 ntained in the f
2e920 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a ile zFile..**.**
2e930 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e ^The entry poin
2e940 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e t is zProc..** ^
2e950 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 zProc may be 0,
2e960 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 in which case th
2e970 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e e name of the en
2e980 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 try point.** def
2e990 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 aults to "sqlite
2e9a0 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 3_extension_init
2e9b0 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 "..** ^The sqlit
2e9c0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f e3_load_extensio
2e9d0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 n() interface re
2e9e0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 turns.** [SQLITE
2e9f0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 _OK] on success
2ea00 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f and [SQLITE_ERRO
2ea10 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 R] if something
2ea20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e goes wrong..** ^
2ea30 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 If an error occu
2ea40 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 rs and pzErrMsg
2ea50 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 is not 0, then t
2ea60 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c he.** [sqlite3_l
2ea70 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d oad_extension()]
2ea80 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c interface shall
2ea90 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 attempt to.** f
2eaa0 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 ill *pzErrMsg wi
2eab0 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 th error message
2eac0 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 text stored in
2ead0 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e memory.** obtain
2eae0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
2eaf0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 _malloc()]. The
2eb00 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e calling function
2eb10 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20 .** should free
2eb20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 this memory by c
2eb30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2eb40 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e free()]..**.** ^
2eb50 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e Extension loadin
2eb60 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 g must be enable
2eb70 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 d using.** [sqli
2eb80 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f te3_enable_load_
2eb90 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 extension()] pri
2eba0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 or to calling th
2ebb0 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 is API,.** other
2ebc0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 wise an error wi
2ebd0 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a ll be returned..
2ebe0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 **.** See also t
2ebf0 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 he [load_extensi
2ec00 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f on() SQL functio
2ec10 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 n]..*/.int sqlit
2ec20 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f e3_load_extensio
2ec30 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 n(. sqlite3 *db
2ec40 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f , /* Lo
2ec50 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e ad the extension
2ec60 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 into this datab
2ec70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a ase connection *
2ec80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2ec90 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d zFile, /* Nam
2eca0 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 e of the shared
2ecb0 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 library containi
2ecc0 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a ng extension */.
2ecd0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 const char *zP
2ece0 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 roc, /* Entry
2ecf0 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 point. Derived
2ed00 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 from zFile if 0
2ed10 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 */. char **pzE
2ed20 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 rrMsg /* P
2ed30 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 ut error message
2ed40 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a here if not 0 *
2ed50 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
2ed60 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 3REF: Enable Or
2ed70 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f Disable Extensio
2ed80 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 n Loading.**.**
2ed90 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 ^So as not to op
2eda0 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 en security hole
2edb0 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 s in older appli
2edc0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 cations that are
2edd0 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 .** unprepared t
2ede0 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 o deal with exte
2edf0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 nsion loading, a
2ee00 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 nd as a means of
2ee10 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 disabling.** ex
2ee20 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 tension loading
2ee30 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 while evaluating
2ee40 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
2ee50 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 L, the following
2ee60 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 API.** is provi
2ee70 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 ded to turn the
2ee80 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 [sqlite3_load_ex
2ee90 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 tension()] mecha
2eea0 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e nism on and off.
2eeb0 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f .**.** ^Extensio
2eec0 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 n loading is off
2eed0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 by default. See
2eee0 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a ticket #1863..*
2eef0 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 * ^Call the sqli
2ef00 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f te3_enable_load_
2ef10 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 extension() rout
2ef20 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d ine with onoff==
2ef30 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 1.** to turn ext
2ef40 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f ension loading o
2ef50 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 n and call it wi
2ef60 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 th onoff==0 to t
2ef70 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f urn.** it back o
2ef80 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 ff again..*/.int
2ef90 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f sqlite3_enable_
2efa0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 load_extension(s
2efb0 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 qlite3 *db, int
2efc0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
2efd0 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 API3REF: Automat
2efe0 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 ically Load An E
2eff0 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 xtensions.**.**
2f000 5e 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 ^This API can be
2f010 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 invoked at prog
2f020 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f ram startup in o
2f030 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 rder to register
2f040 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 .** one or more
2f050 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 statically linke
2f060 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 d extensions tha
2f070 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 t will be availa
2f080 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 ble.** to all ne
2f090 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e w [database conn
2f0a0 65 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 ections]..**.**
2f0b0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 ^(This routine s
2f0c0 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 tores a pointer
2f0d0 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e to the extension
2f0e0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 entry point.**
2f0f0 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 in an array that
2f100 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f is obtained fro
2f110 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
2f120 63 28 29 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f c()]. That memo
2f130 72 79 0a 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 ry.** is dealloc
2f140 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ated by [sqlite3
2f150 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 _reset_auto_exte
2f160 6e 73 69 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a nsion()].)^.**.*
2f170 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
2f180 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 registers an ex
2f190 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f tension entry po
2f1a0 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 int that is.** a
2f1b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 utomatically inv
2f1c0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 oked whenever a
2f1d0 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f new [database co
2f1e0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 nnection].** is
2f1f0 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 opened using [sq
2f200 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
2f210 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
2f220 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
2f230 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 3_open_v2()]..**
2f240 20 5e 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 ^Duplicate exte
2f250 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 nsions are detec
2f260 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 ted so calling t
2f270 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d his routine.** m
2f280 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 ultiple times wi
2f290 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 th the same exte
2f2a0 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 nsion is harmles
2f2b0 73 2e 0a 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 s..** ^Automatic
2f2c0 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c extensions appl
2f2d0 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 y across all thr
2f2e0 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c eads..*/.int sql
2f2f0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 ite3_auto_extens
2f300 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 ion(void (*xEntr
2f310 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a yPoint)(void));.
2f320 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2f330 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 Reset Automatic
2f340 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 Extension Loadi
2f350 6e 67 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 ng.**.** ^(This
2f360 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 function disable
2f370 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 s all previously
2f380 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f registered auto
2f390 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 matic.** extensi
2f3a0 6f 6e 73 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 ons. It undoes t
2f3b0 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c he effect of all
2f3c0 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 prior.** [sqlit
2f3d0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f e3_auto_extensio
2f3e0 6e 28 29 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a n()] calls.)^.**
2f3f0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
2f400 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f on disables auto
2f410 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 matic extensions
2f420 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e in all threads.
2f430 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
2f440 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 _reset_auto_exte
2f450 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a nsion(void);../*
2f460 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 .****** EXPERIME
2f470 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 NTAL - subject t
2f480 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 o change without
2f490 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a notice ********
2f4a0 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 ******.**.** The
2f4b0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 interface to th
2f4c0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
2f4d0 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 mechanism is cur
2f4e0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 rently considere
2f4f0 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 d.** to be exper
2f500 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e imental. The in
2f510 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 terface might ch
2f520 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 ange in incompat
2f530 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 ible ways..** If
2f540 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c this is a probl
2f550 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e em for you, do n
2f560 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 ot use the inter
2f570 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d face at this tim
2f580 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
2f590 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
2f5a0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c mechanism stabil
2f5b0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 izes, we will de
2f5c0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 clare the.** int
2f5d0 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 erface fixed, su
2f5e0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e pport it indefin
2f5f0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 itely, and remov
2f600 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a e this comment..
2f610 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 */../*.** Struct
2f620 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 ures used by the
2f630 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 virtual table i
2f640 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 nterface.*/.type
2f650 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
2f660 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f e3_vtab sqlite3_
2f670 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 vtab;.typedef st
2f680 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 ruct sqlite3_ind
2f690 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f ex_info sqlite3_
2f6a0 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 index_info;.type
2f6b0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
2f6c0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 e3_vtab_cursor s
2f6d0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
2f6e0 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 or;.typedef stru
2f6f0 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c ct sqlite3_modul
2f700 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 e sqlite3_module
2f710 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2f720 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 F: Virtual Table
2f730 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f Object.** KEYWO
2f740 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 RDS: sqlite3_mod
2f750 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 ule {virtual tab
2f760 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 le module}.** EX
2f770 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
2f780 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c This structure,
2f790 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 sometimes calle
2f7a0 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 d a a "virtual t
2f7b0 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a able module", .*
2f7c0 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d * defines the im
2f7d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
2f7e0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 a [virtual table
2f7f0 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 s]. .** This st
2f800 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 ructure consists
2f810 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f mostly of metho
2f820 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c ds for the modul
2f830 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 e..**.** ^A virt
2f840 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 ual table module
2f850 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66 is created by f
2f860 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 illing in a pers
2f870 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e istent.** instan
2f880 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 ce of this struc
2f890 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 ture and passing
2f8a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
2f8b0 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 at instance.** t
2f8c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
2f8d0 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b e_module()] or [
2f8e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
2f8f0 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 odule_v2()]..**
2f900 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f ^The registratio
2f910 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 n remains valid
2f920 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c until it is repl
2f930 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72 aced by a differ
2f940 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 ent.** module or
2f950 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 until the [data
2f960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2f970 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f closes. The co
2f980 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 ntent.** of this
2f990 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 structure must
2f9a0 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 not change while
2f9b0 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65 it is registere
2f9c0 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 d with.** any da
2f9d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f9e0 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c n..*/.struct sql
2f9f0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 ite3_module {.
2fa00 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 int iVersion;.
2fa10 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 int (*xCreate)(s
2fa20 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 qlite3*, void *p
2fa30 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 Aux,.
2fa40 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f int argc, co
2fa50 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a nst char *const*
2fa60 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 argv,.
2fa70 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 sqlite3_vta
2fa80 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 b **ppVTab, char
2fa90 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f **);. int (*xCo
2faa0 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c nnect)(sqlite3*,
2fab0 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 void *pAux,.
2fac0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 int
2fad0 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 argc, const char
2fae0 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 *const*argv,.
2faf0 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c sql
2fb00 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 ite3_vtab **ppVT
2fb10 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 ab, char**);. i
2fb20 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 nt (*xBestIndex)
2fb30 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
2fb40 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e VTab, sqlite3_in
2fb50 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e dex_info*);. in
2fb60 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 t (*xDisconnect)
2fb70 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
2fb80 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
2fb90 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 Destroy)(sqlite3
2fba0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
2fbb0 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 int (*xOpen)(sq
2fbc0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
2fbd0 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f b, sqlite3_vtab_
2fbe0 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f cursor **ppCurso
2fbf0 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f r);. int (*xClo
2fc00 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 se)(sqlite3_vtab
2fc10 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 _cursor*);. int
2fc20 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 (*xFilter)(sqli
2fc30 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a te3_vtab_cursor*
2fc40 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f , int idxNum, co
2fc50 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 nst char *idxStr
2fc60 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
2fc70 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 int argc, sqli
2fc80 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 te3_value **argv
2fc90 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 );. int (*xNext
2fca0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
2fcb0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 ursor*);. int (
2fcc0 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 *xEof)(sqlite3_v
2fcd0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 tab_cursor*);.
2fce0 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 int (*xColumn)(s
2fcf0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
2fd00 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e or*, sqlite3_con
2fd10 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 text*, int);. i
2fd20 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c nt (*xRowid)(sql
2fd30 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
2fd40 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
2fd50 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 *pRowid);. int
2fd60 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 (*xUpdate)(sqli
2fd70 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c te3_vtab *, int,
2fd80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a sqlite3_value *
2fd90 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
2fda0 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 *);. int (*xBe
2fdb0 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 gin)(sqlite3_vta
2fdc0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 b *pVTab);. int
2fdd0 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 (*xSync)(sqlite
2fde0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
2fdf0 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 int (*xCommit)
2fe00 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
2fe10 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
2fe20 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 Rollback)(sqlite
2fe30 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
2fe40 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e int (*xFindFun
2fe50 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 ction)(sqlite3_v
2fe60 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 tab *pVtab, int
2fe70 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 nArg, const char
2fe80 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 *zName,.
2fe90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2fea0 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 void (**pxFunc)(
2feb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2fec0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
2fed0 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 ue**),.
2fee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
2fef0 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 id **ppArg);. i
2ff00 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 nt (*xRename)(sq
2ff10 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 lite3_vtab *pVta
2ff20 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a b, const char *z
2ff30 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 New);.};../*.**
2ff40 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 CAPI3REF: Virtua
2ff50 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 l Table Indexing
2ff60 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 Information.**
2ff70 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
2ff80 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 3_index_info.**
2ff90 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
2ffa0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 ** The sqlite3_i
2ffb0 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 ndex_info struct
2ffc0 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 ure and its subs
2ffd0 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 tructures is use
2ffe0 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 d to.** pass inf
2fff0 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e ormation into an
30000 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 d receive the re
30010 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 ply from the [xB
30020 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 estIndex].** met
30030 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 hod of a [virtua
30040 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e l table module].
30050 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 The fields und
30060 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 er **Inputs** ar
30070 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 e the.** inputs
30080 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e to xBestIndex an
30090 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e d are read-only.
300a0 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 xBestIndex ins
300b0 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 erts its.** resu
300c0 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f lts into the **O
300d0 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e utputs** fields.
300e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f .**.** ^(The aCo
300f0 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 nstraint[] array
30100 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 records WHERE c
30110 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 lause constraint
30120 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a s of the form:.*
30130 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e *.** <pre>column
30140 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a OP expr</pre>.*
30150 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 *.** where OP is
30160 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c =, <, <=,
30170 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e >, or >=.
30180 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63 )^ ^(The partic
30190 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 ular operator is
301a0 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 .** stored in aC
301b0 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 29 onstraint[].op.)
301c0 5e 20 20 5e 54 68 65 20 69 6e 64 65 78 20 6f 66 ^ ^The index of
301d0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 the column is s
301e0 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e tored in.** aCon
301f0 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d straint[].iColum
30200 6e 2e 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e n. ^(aConstrain
30210 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 t[].usable is TR
30220 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 UE if the.** exp
30230 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 r on the right-h
30240 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 and side can be
30250 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 evaluated (and t
30260 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 hus the constrai
30270 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 nt.** is usable)
30280 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 and false if it
30290 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a cannot.)^.**.**
302a0 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 ^The optimizer
302b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e automatically in
302c0 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 verts terms of t
302d0 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 he form "expr OP
302e0 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 column".** and
302f0 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 makes other simp
30300 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 lifications to t
30310 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 he WHERE clause
30320 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f in an attempt to
30330 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 .** get as many
30340 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 WHERE clause ter
30350 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d ms into the form
30360 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 shown above as
30370 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 possible..** ^Th
30380 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 e aConstraint[]
30390 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 array only repor
303a0 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ts WHERE clause
303b0 74 65 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a terms that are.*
303c0 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 * relevant to th
303d0 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 e particular vir
303e0 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 tual table being
303f0 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 queried..**.**
30400 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f ^Information abo
30410 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 ut the ORDER BY
30420 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 clause is stored
30430 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a in aOrderBy[]..
30440 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 ** ^Each term of
30450 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 aOrderBy record
30460 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 s a column of th
30470 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
30480 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 e..**.** The [xB
30490 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 estIndex] method
304a0 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 must fill aCons
304b0 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 traintUsage[] wi
304c0 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a th information.*
304d0 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 * about what par
304e0 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 ameters to pass
304f0 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 to xFilter. ^If
30500 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 argvIndex>0 the
30510 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 n.** the right-h
30520 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 and side of the
30530 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 corresponding aC
30540 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 onstraint[] is e
30550 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 valuated.** and
30560 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 becomes the argv
30570 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 Index-th entry i
30580 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43 n argv. ^(If aC
30590 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d onstraintUsage[]
305a0 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 .omit.** is true
305b0 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 , then the const
305c0 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 raint is assumed
305d0 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e to be fully han
305e0 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 dled by the.** v
305f0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 irtual table and
30600 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 is not checked
30610 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e again by SQLite.
30620 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 )^.**.** ^The id
30630 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 xNum and idxPtr
30640 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 values are recor
30650 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 ded and passed i
30660 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c nto the.** [xFil
30670 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 ter] method..**
30680 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 ^[sqlite3_free()
30690 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 ] is used to fre
306a0 65 20 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 e idxPtr if and
306b0 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e 65 65 64 only iff.** need
306c0 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 ToFreeIdxPtr is
306d0 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 true..**.** ^The
306e0 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 orderByConsumed
306f0 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 means that outp
30700 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 ut from [xFilter
30710 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f ]/[xNext] will o
30720 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 ccur in.** the c
30730 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 orrect order to
30740 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 satisfy the ORDE
30750 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 R BY clause so t
30760 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a hat no separate.
30770 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 ** sorting step
30780 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a is required..**.
30790 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74 65 ** ^The estimate
307a0 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 dCost value is a
307b0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 n estimate of th
307c0 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 e cost of doing
307d0 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 the.** particula
307e0 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c r lookup. A ful
307f0 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c l scan of a tabl
30800 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 e with N entries
30810 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 should have.**
30820 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 a cost of N. A
30830 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 binary search of
30840 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e a table of N en
30850 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 tries should hav
30860 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 e a.** cost of a
30870 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 pproximately log
30880 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 (N)..*/.struct s
30890 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 qlite3_index_inf
308a0 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 o {. /* Inputs
308b0 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 */. int nConstr
308c0 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 aint;
308d0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 /* Number of ent
308e0 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 ries in aConstra
308f0 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 int */. struct
30900 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f sqlite3_index_co
30910 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 nstraint {.
30920 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 int iColumn;
30930 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c /* Col
30940 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 umn on left-hand
30950 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 side of constra
30960 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 int */. unsi
30970 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 gned char op;
30980 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 /* Constra
30990 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a int operator */.
309a0 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 unsigned ch
309b0 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f ar usable; /
309c0 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63 * True if this c
309d0 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 onstraint is usa
309e0 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 ble */. int
309f0 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 iTermOffset;
30a00 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e /* Used in
30a10 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 ternally - xBest
30a20 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e Index should ign
30a30 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e ore */. } *aCon
30a40 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 straint;
30a50 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 /* Table of
30a60 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e WHERE clause con
30a70 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e straints */. in
30a80 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 t nOrderBy;
30a90 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 /* Numb
30aa0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 er of terms in t
30ab0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
30ac0 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 se */. struct s
30ad0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 qlite3_index_ord
30ae0 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 erby {. int
30af0 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 iColumn;
30b00 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 /* Column
30b10 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 number */. u
30b20 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 nsigned char des
30b30 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 c; /* True
30b40 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 for DESC. Fals
30b50 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 e for ASC. */.
30b60 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20 } *aOrderBy;
30b70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 /* Th
30b80 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
30b90 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 e */. /* Output
30ba0 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 s */. struct sq
30bb0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 lite3_index_cons
30bc0 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 traint_usage {.
30bd0 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 int argvIndex
30be0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 ; /* i
30bf0 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 f >0, constraint
30c00 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 is part of argv
30c10 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 to xFilter */.
30c20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 unsigned char
30c30 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 omit; /* D
30c40 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 o not code a tes
30c50 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 t for this const
30c60 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 raint */. } *aC
30c70 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a onstraintUsage;.
30c80 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 int idxNum;
30c90 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
30ca0 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 Number used to i
30cb0 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 dentify the inde
30cc0 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 x */. char *idx
30cd0 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 Str;
30ce0 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 /* String, pos
30cf0 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 sibly obtained f
30d00 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c rom sqlite3_mall
30d10 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 oc */. int need
30d20 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 ToFreeIdxStr;
30d30 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 /* Free idxSt
30d40 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f r using sqlite3_
30d50 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a free() if true *
30d60 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 /. int orderByC
30d70 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f onsumed; /
30d80 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 * True if output
30d90 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 is already orde
30da0 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 red */. double
30db0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 estimatedCost;
30dc0 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 /* Estimated
30dd0 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 cost of using t
30de0 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a his index */.};.
30df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
30e00 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
30e10 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 EQ 2.#define
30e20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
30e30 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a STRAINT_GT 4.
30e40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
30e50 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
30e60 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 LE 8.#define
30e70 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
30e80 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 STRAINT_LT 16
30e90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
30ea0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
30eb0 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e _GE 32.#defin
30ec0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
30ed0 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 ONSTRAINT_MATCH
30ee0 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 64../*.** CAPI3R
30ef0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 EF: Register A V
30f00 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 irtual Table Imp
30f10 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 45 lementation.** E
30f20 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
30f30 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
30f40 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 72 65 s are used to re
30f50 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 gister a new [vi
30f60 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 rtual table modu
30f70 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f le] name..** ^Mo
30f80 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 dule names must
30f90 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62 65 be registered be
30fa0 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 fore.** creating
30fb0 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 a new [virtual
30fc0 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 table] using the
30fd0 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65 66 6f module and befo
30fe0 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 re using a.** pr
30ff0 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 eexisting [virtu
31000 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 al table] for th
31010 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 e module..**.**
31020 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 ^The module name
31030 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 6f is registered o
31040 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
31050 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 connection] spec
31060 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 ified.** by the
31070 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
31080 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 ^The name of t
31090 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 he module is giv
310a0 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 en by the .** se
310b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
310c0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 ^The third para
310d0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 meter is a point
310e0 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 er to.** the imp
310f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
31100 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c he [virtual tabl
31110 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 e module]. ^Th
31120 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 e fourth.** para
31130 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 meter is an arbi
31140 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 trary client dat
31150 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 a pointer that i
31160 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 s passed through
31170 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 .** into the [xC
31180 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e reate] and [xCon
31190 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 nect] methods of
311a0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
311b0 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 le module.** whe
311c0 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 n a new virtual
311d0 74 61 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e table is be bein
311e0 67 20 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 g created or rei
311f0 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a nitialized..**.*
31200 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
31210 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 reate_module_v2(
31220 29 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 ) interface has
31230 61 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 a fifth paramete
31240 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 r which.** is a
31250 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 pointer to a des
31260 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 tructor for the
31270 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 pClientData. ^S
31280 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e QLite will.** in
31290 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 voke the destruc
312a0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 tor function (if
312b0 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 it is not NULL)
312c0 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 when SQLite.**
312d0 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 no longer needs
312e0 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20 the pClientData
312f0 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 73 pointer. ^The s
31300 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
31310 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 dule().** interf
31320 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e ace is equivalen
31330 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 t to sqlite3_cre
31340 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 ate_module_v2()
31350 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 with a NULL.** d
31360 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 estructor..*/.SQ
31370 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
31380 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 L int sqlite3_cr
31390 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 eate_module(. s
313a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
313b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c /* SQL
313c0 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ite connection t
313d0 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c o register modul
313e0 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 e with */. cons
313f0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 t char *zName,
31400 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
31410 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a f the module */.
31420 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f const sqlite3_
31430 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 module *p, /*
31440 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 Methods for the
31450 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 module */. void
31460 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 *pClientData
31470 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 /* Client
31480 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 data for xCreat
31490 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b e/xConnect */.);
314a0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
314b0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
314c0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 _create_module_v
314d0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
314e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
314f0 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 /* SQLite connec
31500 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 tion to register
31510 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a module with */.
31520 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
31530 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 ame, /*
31540 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 Name of the modu
31550 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 le */. const sq
31560 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c lite3_module *p,
31570 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f /* Methods fo
31580 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a r the module */.
31590 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 void *pClientD
315a0 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 ata, /*
315b0 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 Client data for
315c0 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 xCreate/xConnect
315d0 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 */. void(*xDes
315e0 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 troy)(void*)
315f0 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 /* Module destr
31600 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a uctor function *
31610 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
31620 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 3REF: Virtual Ta
31630 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a ble Instance Obj
31640 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
31650 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a sqlite3_vtab.**
31660 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
31670 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 .** Every [virtu
31680 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d al table module]
31690 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
316a0 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a uses a subclass.
316b0 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ** of this objec
316c0 74 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 t to describe a
316d0 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 particular insta
316e0 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 nce.** of the [v
316f0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 irtual table].
31700 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 Each subclass wi
31710 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 ll.** be tailore
31720 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 d to the specifi
31730 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d c needs of the m
31740 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 odule implementa
31750 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 tion..** The pur
31760 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 pose of this sup
31770 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 erclass is to de
31780 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 fine certain fie
31790 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 lds that are.**
317a0 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f common to all mo
317b0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 dule implementat
317c0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 ions..**.** ^Vir
317d0 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 tual tables meth
317e0 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 ods can set an e
317f0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 rror message by
31800 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 assigning a.** s
31810 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 tring obtained f
31820 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 rom [sqlite3_mpr
31830 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d intf()] to zErrM
31840 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 sg. The method
31850 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 should.** take c
31860 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 are that any pri
31870 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 or string is fre
31880 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 ed by a call to
31890 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
318a0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 .** prior to ass
318b0 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 igning a new str
318c0 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 ing to zErrMsg.
318d0 20 5e 41 66 74 65 72 20 74 68 65 20 65 72 72 6f ^After the erro
318e0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 r message.** is
318f0 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 delivered up to
31900 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 the client appli
31910 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 cation, the stri
31920 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d ng will be autom
31930 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 atically.** free
31940 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 d by sqlite3_fre
31950 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 e() and the zErr
31960 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 Msg field will b
31970 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 e zeroed..*/.str
31980 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 uct sqlite3_vtab
31990 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 {. const sqlit
319a0 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 e3_module *pModu
319b0 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 le; /* The modu
319c0 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 le for this virt
319d0 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 ual table */. i
319e0 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 nt nRef;
319f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
31a00 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 * NO LONGER USED
31a10 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 */. char *zErr
31a20 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 Msg;
31a30 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
31a40 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 essage from sqli
31a50 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f te3_mprintf() */
31a60 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 . /* Virtual ta
31a70 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
31a80 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c ons will typical
31a90 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 ly add additiona
31aa0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a l fields */.};..
31ab0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31ac0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 Virtual Table Cu
31ad0 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b rsor Object.** K
31ae0 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 EYWORDS: sqlite3
31af0 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 _vtab_cursor {vi
31b00 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 rtual table curs
31b10 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e or}.** EXPERIMEN
31b20 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 TAL.**.** Every
31b30 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d [virtual table m
31b40 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 odule] implement
31b50 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 ation uses a sub
31b60 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 class of the.**
31b70 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 following struct
31b80 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 ure to describe
31b90 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 cursors that poi
31ba0 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b nt into the.** [
31bb0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 virtual table] a
31bc0 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 nd are used.** t
31bd0 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 o loop through t
31be0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 he virtual table
31bf0 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 . Cursors are c
31c00 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 reated using the
31c10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 .** [sqlite3_mod
31c20 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 ule.xOpen | xOpe
31c30 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 n] method of the
31c40 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 module and are
31c50 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 destroyed.** by
31c60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 the [sqlite3_mod
31c70 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c ule.xClose | xCl
31c80 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 ose] method. Cu
31c90 72 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a rsors are used.*
31ca0 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 * by the [xFilte
31cb0 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 r], [xNext], [xE
31cc0 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 of], [xColumn],
31cd0 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 and [xRowid] met
31ce0 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d hods.** of the m
31cf0 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 odule. Each mod
31d00 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
31d10 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a on will define.*
31d20 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
31d30 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 a cursor struct
31d40 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 ure to suit its
31d50 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a own needs..**.**
31d60 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 This superclass
31d70 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 exists in order
31d80 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 to define field
31d90 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 s of the cursor
31da0 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d that.** are comm
31db0 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d on to all implem
31dc0 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 entations..*/.st
31dd0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 ruct sqlite3_vta
31de0 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c b_cursor {. sql
31df0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
31e00 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 ; /* Virtua
31e10 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 l table of this
31e20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 cursor */. /* V
31e30 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 irtual table imp
31e40 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c lementations wil
31e50 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 l typically add
31e60 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 additional field
31e70 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 s */.};../*.** C
31e80 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 API3REF: Declare
31e90 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 The Schema Of A
31ea0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a Virtual Table.*
31eb0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
31ec0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 *.** ^The [xCrea
31ed0 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 te] and [xConnec
31ee0 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a t] methods of a.
31ef0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ** [virtual tabl
31f00 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 e module] call t
31f10 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a his interface.**
31f20 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 to declare the
31f30 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 format (the name
31f40 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 s and datatypes
31f50 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 of the columns)
31f60 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 of.** the virtua
31f70 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d l tables they im
31f80 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 plement..*/.SQLI
31f90 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
31fa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c int sqlite3_decl
31fb0 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 are_vtab(sqlite3
31fc0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
31fd0 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 SQL);../*.** CAP
31fe0 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 I3REF: Overload
31ff0 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 A Function For A
32000 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a Virtual Table.*
32010 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
32020 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 *.** ^(Virtual t
32030 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 ables can provid
32040 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d e alternative im
32050 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
32060 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 functions.** us
32070 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 ing the [xFindFu
32080 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f nction] method o
32090 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 f the [virtual t
320a0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a able module]. .
320b0 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 ** But global ve
320c0 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 rsions of those
320d0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 functions.** mus
320e0 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 t exist in order
320f0 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 to be overloade
32100 64 2e 29 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 d.).**.** ^(This
32110 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 API makes sure
32120 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e a global version
32130 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 of a function w
32140 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 ith a particular
32150 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d .** name and num
32160 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 ber of parameter
32170 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f s exists. If no
32180 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 such function e
32190 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 xists.** before
321a0 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c this API is call
321b0 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 ed, a new functi
321c0 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e on is created.)^
321d0 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ^The implement
321e0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 ation.** of the
321f0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 new function alw
32200 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 ays causes an ex
32210 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 ception to be th
32220 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 rown. So.** the
32230 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 new function is
32240 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e not good for an
32250 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 ything by itself
32260 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 . Its only.** p
32270 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 urpose is to be
32280 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 a placeholder fu
32290 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 nction that can
322a0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a be overloaded.**
322b0 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 by a [virtual t
322c0 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 able]..*/.SQLITE
322d0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
322e0 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f t sqlite3_overlo
322f0 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 ad_function(sqli
32300 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 te3*, const char
32310 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 *zFuncName, int
32320 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 nArg);../*.** T
32330 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 he interface to
32340 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c the virtual-tabl
32350 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 e mechanism defi
32360 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 ned above (back
32370 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 up.** to a comme
32380 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 nt remarkably si
32390 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e milar to this on
323a0 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 e) is currently
323b0 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f considered.** to
323c0 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c be experimental
323d0 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 . The interface
323e0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e might change in
323f0 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 incompatible wa
32400 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 ys..** If this i
32410 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 s a problem for
32420 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 you, do not use
32430 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 the interface at
32440 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a this time..**.*
32450 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 * When the virtu
32460 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 al-table mechani
32470 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 sm stabilizes, w
32480 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 e will declare t
32490 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 he.** interface
324a0 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 fixed, support i
324b0 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 t indefinitely,
324c0 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 and remove this
324d0 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a comment..**.****
324e0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 ** EXPERIMENTAL
324f0 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 - subject to cha
32500 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 nge without noti
32510 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ce *************
32520 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *.*/../*.** CAPI
32530 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 3REF: A Handle T
32540 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a o An Open BLOB.*
32550 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f * KEYWORDS: {BLO
32560 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 B handle} {BLOB
32570 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 handles}.**.** A
32580 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
32590 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 is object repres
325a0 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f ents an open BLO
325b0 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 B on which.** [s
325c0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
325d0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 | incremental B
325e0 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 LOB I/O] can be
325f0 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f performed..** ^O
32600 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 bjects of this t
32610 79 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20 ype are created
32620 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 by [sqlite3_blob
32630 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 _open()].** and
32640 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 destroyed by [sq
32650 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
32660 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 ()]..** ^The [sq
32670 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
32680 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
32690 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e blob_write()] in
326a0 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 terfaces.** can
326b0 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 be used to read
326c0 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 or write small s
326d0 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 ubsections of th
326e0 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 e BLOB..** ^The
326f0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 [sqlite3_blob_by
32700 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tes()] interface
32710 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a returns the siz
32720 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e e of the BLOB in
32730 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 bytes..*/.typed
32740 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
32750 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 3_blob sqlite3_b
32760 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lob;../*.** CAPI
32770 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 3REF: Open A BLO
32780 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 B For Incrementa
32790 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 l I/O.**.** ^(Th
327a0 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 is interfaces op
327b0 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 ens a [BLOB hand
327c0 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 le | handle] to
327d0 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 the BLOB located
327e0 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c .** in row iRow,
327f0 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c column zColumn,
32800 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e table zTable in
32810 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a database zDb;.*
32820 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * in other words
32830 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 , the same BLOB
32840 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 that would be se
32850 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a lected by:.**.**
32860 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 <pre>.** SE
32870 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f LECT zColumn FRO
32880 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 M zDb.zTable WHE
32890 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f RE [rowid] = iRo
328a0 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a w;.** </pre>)^.*
328b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 *.** ^If the fla
328c0 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 gs parameter is
328d0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 non-zero, then t
328e0 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 he BLOB is opene
328f0 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e d for read.** an
32900 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 d write access.
32910 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 ^If it is zero,
32920 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e the BLOB is open
32930 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 ed for read acce
32940 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f ss..** ^It is no
32950 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 t possible to op
32960 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 en a column that
32970 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 is part of an i
32980 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 ndex or primary
32990 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 .** key for writ
329a0 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 ing. ^If [foreig
329b0 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 n key constraint
329c0 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 s] are enabled,
329d0 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f it is .** not po
329e0 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 ssible to open a
329f0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 column that is
32a00 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 part of a [child
32a10 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e key] for writin
32a20 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 g..**.** ^Note t
32a30 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
32a40 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 name is not the
32a50 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 filename that c
32a60 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 ontains.** the d
32a70 61 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68 atabase but rath
32a80 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 er the symbolic
32a90 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
32aa0 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 base that.** app
32ab0 65 61 72 73 20 61 66 74 65 72 20 74 68 65 20 41 ears after the A
32ac0 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 S keyword when t
32ad0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63 he database is c
32ae0 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b onnected using [
32af0 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 ATTACH]..** ^For
32b00 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 the main databa
32b10 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 se file, the dat
32b20 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d abase name is "m
32b30 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 ain"..** ^For TE
32b40 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 MP tables, the d
32b50 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 atabase name is
32b60 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 "temp"..**.** ^(
32b70 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c On success, [SQL
32b80 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 ITE_OK] is retur
32b90 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 ned and the new
32ba0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 [BLOB handle] is
32bb0 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a written.** to *
32bc0 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 ppBlob. Otherwis
32bd0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
32be0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
32bf0 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 d *ppBlob is set
32c00 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c .** to be a null
32c10 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e pointer.)^.** ^
32c20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 This function se
32c30 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 ts the [database
32c40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 connection] err
32c50 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 or code and mess
32c60 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c age.** accessibl
32c70 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 e via [sqlite3_e
32c80 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 rrcode()] and [s
32c90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
32ca0 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 and related.**
32cb0 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 functions. ^Note
32cc0 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f that the *ppBlo
32cd0 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c b variable is al
32ce0 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 ways initialized
32cf0 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 in a.** way tha
32d00 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 t makes it safe
32d10 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 to invoke [sqlit
32d20 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d e3_blob_close()]
32d30 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 on *ppBlob.** r
32d40 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 egardless of the
32d50 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c success or fail
32d60 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ure of this rout
32d70 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 ine..**.** ^(If
32d80 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 the row that a B
32d90 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 LOB handle point
32da0 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 s to is modified
32db0 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 by an.** [UPDAT
32dc0 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 E], [DELETE], or
32dd0 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 by [ON CONFLICT
32de0 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a ] side-effects.*
32df0 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 * then the BLOB
32e00 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 handle is marked
32e10 20 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a as "expired"..*
32e20 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 * This is true i
32e30 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 f any column of
32e40 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 the row is chang
32e50 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d ed, even a colum
32e60 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 n.** other than
32e70 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 the one the BLOB
32e80 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 handle is open
32e90 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 on.)^.** ^Calls
32ea0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 to [sqlite3_blob
32eb0 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 _read()] and [sq
32ec0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 lite3_blob_write
32ed0 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 ()] for.** a exp
32ee0 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 ired BLOB handle
32ef0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 fail with an re
32f00 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 turn code of [SQ
32f10 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 LITE_ABORT]..**
32f20 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 ^(Changes writte
32f30 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 n into a BLOB pr
32f40 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 ior to the BLOB
32f50 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 expiring are not
32f60 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 .** rolled back
32f70 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f by the expiratio
32f80 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 n of the BLOB.
32f90 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c Such changes wil
32fa0 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 l eventually.**
32fb0 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 commit if the tr
32fc0 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e ansaction contin
32fd0 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f ues to completio
32fe0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 n.)^.**.** ^Use
32ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f the [sqlite3_blo
33000 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 b_bytes()] inter
33010 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e face to determin
33020 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a e the size of.**
33030 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 the opened blob
33040 2e 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 . ^The size of
33050 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 a blob may not b
33060 65 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 e changed by thi
33070 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 s.** interface.
33080 20 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 Use the [UPDATE
33090 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f ] SQL command to
330a0 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 change the size
330b0 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a of a.** blob..*
330c0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
330d0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
330e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
330f0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 _result_zeroblob
33100 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a ()] interfaces.*
33110 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d * and the built-
33120 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 in [zeroblob] SQ
33130 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 L function can b
33140 65 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 e used, if desir
33150 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 ed,.** to create
33160 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d an empty, zero-
33170 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 filled blob in w
33180 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 hich to read or
33190 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 write using.** t
331a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a his interface..*
331b0 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 *.** To avoid a
331c0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 resource leak, e
331d0 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 very open [BLOB
331e0 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 handle] should e
331f0 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 ventually.** be
33200 72 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 released by a ca
33210 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ll to [sqlite3_b
33220 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f lob_close()]..*/
33230 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f .int sqlite3_blo
33240 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 b_open(. sqlite
33250 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 3*,. const char
33260 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 *zDb,. const c
33270 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 har *zTable,. c
33280 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 onst char *zColu
33290 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e mn,. sqlite3_in
332a0 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 t64 iRow,. int
332b0 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 flags,. sqlite3
332c0 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 _blob **ppBlob.)
332d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
332e0 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 F: Close A BLOB
332f0 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c Handle.**.** ^Cl
33300 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c oses an open [BL
33310 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a OB handle]..**.*
33320 2a 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f * ^Closing a BLO
33330 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 B shall cause th
33340 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 e current transa
33350 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a ction to commit.
33360 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20 ** if there are
33370 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 no other BLOBs,
33380 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 no pending prepa
33390 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 red statements,
333a0 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 and the.** datab
333b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
333c0 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 s in [autocommit
333d0 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 mode]..** ^If a
333e0 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d ny writes were m
333f0 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c ade to the BLOB,
33400 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 they might be h
33410 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 eld in cache.**
33420 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 until the close
33430 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 operation if the
33440 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a y will fit..**.*
33450 2a 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 * ^(Closing the
33460 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 BLOB often force
33470 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a s the changes.**
33480 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 out to disk and
33490 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 so if any I/O e
334a0 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 rrors occur, the
334b0 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 y will likely oc
334c0 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 cur.** at the ti
334d0 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 me when the BLOB
334e0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 is closed. Any
334f0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 errors that occ
33500 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f ur during.** clo
33510 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 sing are reporte
33520 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 d as a non-zero
33530 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a return value.)^.
33540 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 **.** ^(The BLOB
33550 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e is closed uncon
33560 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 ditionally. Eve
33570 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e n if this routin
33580 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 e returns.** an
33590 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 error code, the
335a0 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c BLOB is still cl
335b0 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 osed.)^.**.** ^C
335c0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 alling this rout
335d0 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 ine with a null
335e0 70 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 pointer (such as
335f0 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e would be return
33600 65 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 ed.** by a faile
33610 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 d call to [sqlit
33620 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 e3_blob_open()])
33630 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e is a harmless n
33640 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c o-op..*/.int sql
33650 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 ite3_blob_close(
33660 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b sqlite3_blob *);
33670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
33680 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a : Return The Siz
33690 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f e Of An Open BLO
336a0 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 B.**.** ^Returns
336b0 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 the size in byt
336c0 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 es of the BLOB a
336d0 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 ccessible via th
336e0 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c e .** successful
336f0 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 ly opened [BLOB
33700 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f handle] in its o
33710 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e nly argument. ^
33720 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 The.** increment
33730 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 al blob I/O rout
33740 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 ines can only re
33750 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e ad or overwritin
33760 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c g existing.** bl
33770 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 ob content; they
33780 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 cannot change t
33790 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f he size of a blo
337a0 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f b..**.** This ro
337b0 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 utine only works
337c0 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 on a [BLOB hand
337d0 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 le] which has be
337e0 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 en created.** by
337f0 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 a prior success
33800 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
33810 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 ite3_blob_open()
33820 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 ] and which has
33830 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 not.** been clos
33840 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 ed by [sqlite3_b
33850 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 lob_close()]. P
33860 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 assing any other
33870 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 pointer in.** t
33880 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 o this routine r
33890 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 esults in undefi
338a0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 ned and probably
338b0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 undesirable beh
338c0 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 avior..*/.int sq
338d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 lite3_blob_bytes
338e0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 (sqlite3_blob *)
338f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
33900 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f F: Read Data Fro
33910 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 m A BLOB Increme
33920 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 ntally.**.** ^(T
33930 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
33940 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 used to read dat
33950 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b a from an open [
33960 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 BLOB handle] int
33970 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 o a.** caller-su
33980 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e pplied buffer. N
33990 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 bytes of data a
339a0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 re copied into b
339b0 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 uffer Z.** from
339c0 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 the open BLOB, s
339d0 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 tarting at offse
339e0 74 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a t iOffset.)^.**.
339f0 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f ** ^If offset iO
33a00 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 ffset is less th
33a10 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 an N bytes from
33a20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 the end of the B
33a30 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f LOB,.** [SQLITE_
33a40 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e ERROR] is return
33a50 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 ed and no data i
33a60 73 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f s read. ^If N o
33a70 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 r iOffset is.**
33a80 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 less than zero,
33a90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
33aa0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e s returned and n
33ab0 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a o data is read..
33ac0 2a 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 ** ^The size of
33ad0 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 the blob (and he
33ae0 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 nce the maximum
33af0 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 value of N+iOffs
33b00 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 et).** can be de
33b10 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 termined using t
33b20 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
33b30 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
33b40 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 ace..**.** ^An a
33b50 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 ttempt to read f
33b60 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b rom an expired [
33b70 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 BLOB handle] fai
33b80 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 ls with an.** er
33b90 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c ror code of [SQL
33ba0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a ITE_ABORT]..**.*
33bb0 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 * ^(On success,
33bc0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 sqlite3_blob_rea
33bd0 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 d() returns SQLI
33be0 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 TE_OK..** Otherw
33bf0 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 ise, an [error c
33c00 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 ode] or an [exte
33c10 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
33c20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a is returned.)^.
33c30 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
33c40 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e ne only works on
33c50 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d a [BLOB handle]
33c60 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 which has been
33c70 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 created.** by a
33c80 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c prior successful
33c90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
33ca0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 3_blob_open()] a
33cb0 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 nd which has not
33cc0 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 .** been closed
33cd0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 by [sqlite3_blob
33ce0 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 _close()]. Pass
33cf0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f ing any other po
33d00 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 inter in.** to t
33d10 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 his routine resu
33d20 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 lts in undefined
33d30 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e and probably un
33d40 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 desirable behavi
33d50 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c or..**.** See al
33d60 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f so: [sqlite3_blo
33d70 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 b_write()]..*/.i
33d80 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
33d90 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f read(sqlite3_blo
33da0 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e b *, void *Z, in
33db0 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 t N, int iOffset
33dc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
33dd0 45 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 EF: Write Data I
33de0 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 nto A BLOB Incre
33df0 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e mentally.**.** ^
33e00 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 This function is
33e10 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 used to write d
33e20 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e ata into an open
33e30 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 [BLOB handle] f
33e40 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d rom a.** caller-
33e50 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e supplied buffer.
33e60 20 5e 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 ^N bytes of dat
33e70 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f a are copied fro
33e80 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a m the buffer Z.*
33e90 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 * into the open
33ea0 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 BLOB, starting a
33eb0 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 t offset iOffset
33ec0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
33ed0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 [BLOB handle] pa
33ee0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 ssed as the firs
33ef0 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e t argument was n
33f00 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a ot opened for.**
33f10 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c writing (the fl
33f20 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f ags parameter to
33f30 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
33f40 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 pen()] was zero)
33f50 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 ,.** this functi
33f60 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 on returns [SQLI
33f70 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a TE_READONLY]..**
33f80 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
33f90 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 on may only modi
33fa0 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 fy the contents
33fb0 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 of the BLOB; it
33fc0 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 is.** not possib
33fd0 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 le to increase t
33fe0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f he size of a BLO
33ff0 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 B using this API
34000 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 ..** ^If offset
34010 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 iOffset is less
34020 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f than N bytes fro
34030 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 m the end of the
34040 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 BLOB,.** [SQLIT
34050 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 E_ERROR] is retu
34060 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 rned and no data
34070 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 is written. ^I
34080 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 f N is.** less t
34090 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 han zero [SQLITE
340a0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 _ERROR] is retur
340b0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 ned and no data
340c0 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 is written..** T
340d0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 he size of the B
340e0 4c 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 LOB (and hence t
340f0 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 he maximum value
34100 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a of N+iOffset).*
34110 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 * can be determi
34120 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 ned using the [s
34130 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 qlite3_blob_byte
34140 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a s()] interface..
34150 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 **.** ^An attemp
34160 74 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e t to write to an
34170 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 expired [BLOB h
34180 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 andle] fails wit
34190 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f h an.** error co
341a0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 de of [SQLITE_AB
341b0 4f 52 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 ORT]. ^Writes t
341c0 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 o the BLOB that
341d0 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f occurred.** befo
341e0 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e re the [BLOB han
341f0 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 dle] expired are
34200 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b not rolled back
34210 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 by the.** expir
34220 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e ation of the han
34230 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 dle, though of c
34240 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e ourse those chan
34250 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 ges might.** hav
34260 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 e been overwritt
34270 65 6e 20 62 79 20 74 68 65 20 73 74 61 74 65 6d en by the statem
34280 65 6e 74 20 74 68 61 74 20 65 78 70 69 72 65 64 ent that expired
34290 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 the BLOB handle
342a0 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 .** or by other
342b0 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 independent stat
342c0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ements..**.** ^(
342d0 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 On success, sqli
342e0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 te3_blob_write()
342f0 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
34300 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 OK..** Otherwise
34310 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 , an [error cod
34320 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 e] or an [extend
34330 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 ed error code] i
34340 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a s returned.)^.**
34350 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
34360 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 only works on a
34370 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 [BLOB handle] w
34380 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 hich has been cr
34390 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 eated.** by a pr
343a0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
343b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
343c0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 blob_open()] and
343d0 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a which has not.*
343e0 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 * been closed by
343f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 [sqlite3_blob_c
34400 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e lose()]. Passin
34410 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e g any other poin
34420 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 ter in.** to thi
34430 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 s routine result
34440 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 s in undefined a
34450 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 nd probably unde
34460 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 sirable behavior
34470 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
34480 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f : [sqlite3_blob_
34490 72 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 read()]..*/.int
344a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 sqlite3_blob_wri
344b0 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 te(sqlite3_blob
344c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a *, const void *z
344d0 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 , int n, int iOf
344e0 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 fset);../*.** CA
344f0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
34500 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 File System Obje
34510 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 cts.**.** A virt
34520 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 ual filesystem (
34530 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 VFS) is an [sqli
34540 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a te3_vfs] object.
34550 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 ** that SQLite u
34560 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a ses to interact.
34570 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 ** with the unde
34580 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 rlying operating
34590 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 system. Most S
345a0 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d QLite builds com
345b0 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 e with a.** sing
345c0 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 le default VFS t
345d0 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 hat is appropria
345e0 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 te for the host
345f0 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 computer..** New
34600 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 VFSes can be re
34610 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 gistered and exi
34620 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 sting VFSes can
34630 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e be unregistered.
34640 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e .** The followin
34650 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 g interfaces are
34660 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a provided..**.**
34670 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 ^The sqlite3_vf
34680 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 s_find() interfa
34690 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
346a0 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 nter to a VFS gi
346b0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a ven its name..**
346c0 20 5e 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 ^Names are case
346d0 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e sensitive..** ^
346e0 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 Names are zero-t
346f0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
34700 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 strings..** ^If
34710 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 there is no matc
34720 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 h, a NULL pointe
34730 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
34740 2a 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 * ^If zVfsName i
34750 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 s NULL then the
34760 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 default VFS is r
34770 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
34780 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 New VFSes are re
34790 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 gistered with sq
347a0 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
347b0 65 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e er()..** ^Each n
347c0 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 ew VFS becomes t
347d0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 he default VFS i
347e0 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 f the makeDflt f
347f0 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e lag is set..** ^
34800 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e The same VFS can
34810 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d be registered m
34820 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 ultiple times wi
34830 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a thout injury..**
34840 20 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 ^To make an exi
34850 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 sting VFS into t
34860 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 he default VFS,
34870 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 register it agai
34880 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 n.** with the ma
34890 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e keDflt flag set.
348a0 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 If two differe
348b0 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68 nt VFSes with th
348c0 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 e.** same name a
348d0 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 re registered, t
348e0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
348f0 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a ndefined. If a.
34900 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74 ** VFS is regist
34910 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 ered with a name
34920 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 that is NULL or
34930 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
34940 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 ,.** then the be
34950 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
34960 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 ned..**.** ^Unre
34970 67 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 gister a VFS wit
34980 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 h the sqlite3_vf
34990 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 s_unregister() i
349a0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 nterface..** ^(I
349b0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 f the default VF
349c0 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 S is unregistere
349d0 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 d, another VFS i
349e0 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 s chosen as.** t
349f0 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 he default. The
34a00 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 choice for the
34a10 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74 new VFS is arbit
34a20 72 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 rary.)^.*/.sqlit
34a30 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f e3_vfs *sqlite3_
34a40 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 vfs_find(const c
34a50 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a har *zVfsName);.
34a60 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f int sqlite3_vfs_
34a70 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 register(sqlite3
34a80 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 _vfs*, int makeD
34a90 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 flt);.int sqlite
34aa0 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
34ab0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a (sqlite3_vfs*);.
34ac0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
34ad0 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 Mutexes.**.** T
34ae0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 he SQLite core u
34af0 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e ses these routin
34b00 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a es for thread.**
34b10 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e synchronization
34b20 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 . Though they ar
34b30 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 e intended for i
34b40 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 nternal.** use b
34b50 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 y SQLite, code t
34b60 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 hat links agains
34b70 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 t SQLite is.** p
34b80 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 ermitted to use
34b90 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 any of these rou
34ba0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tines..**.** The
34bb0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 SQLite source c
34bc0 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c ode contains mul
34bd0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
34be0 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 tions.** of thes
34bf0 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 e mutex routines
34c00 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 . An appropriat
34c10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
34c20 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 .** is selected
34c30 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 automatically at
34c40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 compile-time.
34c50 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a ^(The following.
34c60 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
34c70 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 ns are available
34c80 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 in the SQLite c
34c90 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ore:.**.** <ul>.
34ca0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 ** <li> SQLITE
34cb0 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c _MUTEX_OS2.** <l
34cc0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 i> SQLITE_MUTE
34cd0 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 X_PTHREAD.** <li
34ce0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 > SQLITE_MUTEX
34cf0 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 _W32.** <li> S
34d00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 QLITE_MUTEX_NOOP
34d10 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a .** </ul>)^.**.*
34d20 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 * ^The SQLITE_MU
34d30 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 TEX_NOOP impleme
34d40 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 ntation is a set
34d50 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 of routines.**
34d60 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 that does no rea
34d70 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 l locking and is
34d80 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 appropriate for
34d90 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e use in.** a sin
34da0 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 gle-threaded app
34db0 6c 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 lication. ^The
34dc0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 SQLITE_MUTEX_OS2
34dd0 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 ,.** SQLITE_MUTE
34de0 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 X_PTHREAD, and S
34df0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 QLITE_MUTEX_W32
34e00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a implementations.
34e10 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 ** are appropria
34e20 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 te for use on OS
34e30 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 /2, Unix, and Wi
34e40 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 ndows..**.** ^(I
34e50 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
34e60 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 iled with the SQ
34e70 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 LITE_MUTEX_APPDE
34e80 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a F preprocessor.*
34e90 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 * macro defined
34ea0 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f (with "-DSQLITE_
34eb0 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 MUTEX_APPDEF=1")
34ec0 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a , then no mutex.
34ed0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
34ee0 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 n is included wi
34ef0 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 th the library.
34f00 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 In this case the
34f10 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 .** application
34f20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 must supply a cu
34f30 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 stom mutex imple
34f40 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 mentation using
34f50 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 the.** [SQLITE_C
34f60 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 ONFIG_MUTEX] opt
34f70 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ion of the sqlit
34f80 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 e3_config() func
34f90 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 tion.** before c
34fa0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 alling sqlite3_i
34fb0 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 nitialize() or a
34fc0 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 ny other public
34fd0 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 sqlite3_.** func
34fe0 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 tion that calls
34ff0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
35000 7a 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 ze().)^.**.** ^T
35010 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
35020 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 _alloc() routine
35030 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 allocates a new
35040 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 .** mutex and re
35050 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
35060 74 6f 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 to it. ^If it re
35070 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 turns NULL.** th
35080 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 at means that a
35090 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 mutex could not
350a0 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e be allocated. ^
350b0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 SQLite.** will u
350c0 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 nwind its stack
350d0 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 and return an er
350e0 72 6f 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 ror. ^(The argu
350f0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 ment.** to sqlit
35100 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
35110 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 is one of these
35120 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
35130 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ts:.**.** <ul>.*
35140 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
35150 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 UTEX_FAST.** <li
35160 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
35170 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 RECURSIVE.** <li
35180 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
35190 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a STATIC_MASTER.**
351a0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
351b0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a TEX_STATIC_MEM.*
351c0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
351d0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 UTEX_STATIC_MEM2
351e0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
351f0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 _MUTEX_STATIC_PR
35200 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 NG.** <li> SQLI
35210 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
35220 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c LRU.** <li> SQL
35230 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
35240 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e _LRU2.** </ul>)^
35250 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
35260 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 t two constants
35270 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 (SQLITE_MUTEX_FA
35280 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 ST and SQLITE_MU
35290 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a TEX_RECURSIVE).*
352a0 2a 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f * cause sqlite3_
352b0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f mutex_alloc() to
352c0 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 create.** a new
352d0 20 6d 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 mutex. ^The ne
352e0 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 w mutex is recur
352f0 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 sive when SQLITE
35300 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 _MUTEX_RECURSIVE
35310 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 .** is used but
35320 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 not necessarily
35330 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d so when SQLITE_M
35340 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 UTEX_FAST is use
35350 64 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 d..** The mutex
35360 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 implementation d
35370 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
35380 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 make a distincti
35390 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 on.** between SQ
353a0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
353b0 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f SIVE and SQLITE_
353c0 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 MUTEX_FAST if it
353d0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e does.** not wan
353e0 74 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 t to. ^SQLite w
353f0 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 ill only request
35400 20 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 a recursive mut
35410 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 ex in.** cases w
35420 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e here it really n
35430 65 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 eeds one. ^If a
35440 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 faster non-recu
35450 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 rsive mutex.** i
35460 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
35470 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 available on th
35480 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c e host platform,
35490 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 the mutex subsy
354a0 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 stem.** might re
354b0 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 turn such a mute
354c0 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f x in response to
354d0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
354e0 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f ST..**.** ^The o
354f0 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 ther allowed par
35500 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 ameters to sqlit
35510 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
35520 20 28 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 (anything other
35530 0a 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f .** than SQLITE_
35540 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 MUTEX_FAST and S
35550 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
35560 52 53 49 56 45 29 20 65 61 63 68 20 72 65 74 75 RSIVE) each retu
35570 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 rn.** a pointer
35580 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65 to a static pree
35590 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 xisting mutex.
355a0 5e 53 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 ^Six static mute
355b0 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 xes are.** used
355c0 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 by the current v
355d0 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
355e0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
355f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 ns of SQLite.**
35600 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e may add addition
35610 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 al static mutexe
35620 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 s. Static mutex
35630 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 es are for inter
35640 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 nal.** use by SQ
35650 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c Lite only. Appl
35660 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 ications that us
35670 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 e SQLite mutexes
35680 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f should.** use o
35690 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 nly the dynamic
356a0 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 mutexes returned
356b0 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 by SQLITE_MUTEX
356c0 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 _FAST or.** SQLI
356d0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
356e0 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 VE..**.** ^Note
356f0 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 that if one of t
35700 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 he dynamic mutex
35710 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c parameters (SQL
35720 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a ITE_MUTEX_FAST.*
35730 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 * or SQLITE_MUTE
35740 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 X_RECURSIVE) is
35750 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 used then sqlite
35760 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 3_mutex_alloc().
35770 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 ** returns a dif
35780 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 ferent mutex on
35790 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 every call. ^Bu
357a0 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 t for the static
357b0 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c .** mutex types,
357c0 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 the same mutex
357d0 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 is returned on e
357e0 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 very call that h
357f0 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 as.** the same t
35800 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a ype number..**.*
35810 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d * ^The sqlite3_m
35820 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 utex_free() rout
35830 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 ine deallocates
35840 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 a previously.**
35850 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 allocated dynami
35860 63 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 c mutex. ^SQLit
35870 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 e is careful to
35880 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 deallocate every
35890 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 .** dynamic mute
358a0 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 x that it alloca
358b0 74 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 tes. The dynami
358c0 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e c mutexes must n
358d0 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 ot be in.** use
358e0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 when they are de
358f0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 allocated. Atte
35900 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f mpting to deallo
35910 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a cate a static.**
35920 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 mutex results i
35930 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
35940 76 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e vior. ^SQLite n
35950 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 ever deallocates
35960 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 .** a static mut
35970 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ex..**.** ^The s
35980 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 qlite3_mutex_ent
35990 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 er() and sqlite3
359a0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 _mutex_try() rou
359b0 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a tines attempt.**
359c0 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 to enter a mute
359d0 78 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 x. ^If another
359e0 74 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 thread is alread
359f0 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 y within the mut
35a00 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d ex,.** sqlite3_m
35a10 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c utex_enter() wil
35a20 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 l block and sqli
35a30 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 te3_mutex_try()
35a40 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 will return.** S
35a50 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 QLITE_BUSY. ^Th
35a60 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
35a70 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 try() interface
35a80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
35a90 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 OK].** upon succ
35aa0 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e essful entry. ^
35ab0 28 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64 (Mutexes created
35ac0 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 using.** SQLITE
35ad0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 _MUTEX_RECURSIVE
35ae0 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 can be entered
35af0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 multiple times b
35b00 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 y the same threa
35b10 64 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 d..** In such ca
35b20 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 ses the,.** mute
35b30 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 x must be exited
35b40 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 an equal number
35b50 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 of times before
35b60 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a another thread.
35b70 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 ** can enter.)^
35b80 20 5e 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 ^(If the same t
35b90 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 hread tries to e
35ba0 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a nter any other.*
35bb0 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 * kind of mutex
35bc0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 more than once,
35bd0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
35be0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 undefined..** SQ
35bf0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
35c00 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 exhibit.** such
35c10 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 behavior in its
35c20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 own use of mutex
35c30 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f es.)^.**.** ^(So
35c40 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 me systems (for
35c50 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 example, Windows
35c60 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 95) do not supp
35c70 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f ort the operatio
35c80 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 n.** implemented
35c90 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 by sqlite3_mute
35ca0 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f x_try(). On tho
35cb0 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 se systems, sqli
35cc0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a te3_mutex_try().
35cd0 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 ** will always r
35ce0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 eturn SQLITE_BUS
35cf0 59 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 Y. The SQLite c
35d00 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 ore only ever us
35d10 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 es.** sqlite3_mu
35d20 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 tex_try() as an
35d30 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 optimization so
35d40 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62 this is acceptab
35d50 6c 65 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a le behavior.)^.*
35d60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
35d70 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 3_mutex_leave()
35d80 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 routine exits a
35d90 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a mutex that was.*
35da0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 * previously ent
35db0 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 ered by the same
35dc0 20 74 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 thread. ^(The
35dd0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 behavior.** is
35de0 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 undefined if the
35df0 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 mutex is not cu
35e00 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
35e10 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e by the.** callin
35e20 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e g thread or is n
35e30 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c ot currently all
35e40 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 ocated. SQLite
35e50 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f will.** never do
35e60 20 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a either.)^.**.**
35e70 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e ^If the argumen
35e80 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 t to sqlite3_mut
35e90 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 ex_enter(), sqli
35ea0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c te3_mutex_try(),
35eb0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d or.** sqlite3_m
35ec0 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 utex_leave() is
35ed0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
35ee0 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 then all three r
35ef0 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 outines.** behav
35f00 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a e as no-ops..**.
35f10 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
35f20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 lite3_mutex_held
35f30 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
35f40 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 _mutex_notheld()
35f50 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 ]..*/.sqlite3_mu
35f60 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 tex *sqlite3_mut
35f70 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 ex_alloc(int);.v
35f80 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 oid sqlite3_mute
35f90 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d x_free(sqlite3_m
35fa0 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c utex*);.void sql
35fb0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
35fc0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 (sqlite3_mutex*)
35fd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 ;.int sqlite3_mu
35fe0 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f tex_try(sqlite3_
35ff0 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 mutex*);.void sq
36000 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
36010 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a e(sqlite3_mutex*
36020 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
36030 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 EF: Mutex Method
36040 73 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 s Object.** EXPE
36050 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 RIMENTAL.**.** A
36060 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
36070 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 is structure def
36080 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 ines the low-lev
36090 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 el routines.** u
360a0 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 sed to allocate
360b0 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e and use mutexes.
360c0 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 .**.** Usually,
360d0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
360e0 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e x implementation
360f0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 s provided by SQ
36100 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 Lite are.** suff
36110 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 icient, however
36120 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 the user has the
36130 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 option of subst
36140 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d ituting a custom
36150 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
36160 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a on for specializ
36170 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f ed deployments o
36180 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 r systems for wh
36190 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f ich SQLite.** do
361a0 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 es not provide a
361b0 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d suitable implem
361c0 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 entation. In thi
361d0 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 s case, the user
361e0 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 .** creates and
361f0 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 populates an ins
36200 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 tance of this st
36210 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a ructure to pass.
36220 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ** to sqlite3_co
36230 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 nfig() along wit
36240 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f h the [SQLITE_CO
36250 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 NFIG_MUTEX] opti
36260 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 on..** Additiona
36270 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 lly, an instance
36280 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 of this structu
36290 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 re can be used a
362a0 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 s an.** output v
362b0 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 ariable when que
362c0 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d rying the system
362d0 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 for the current
362e0 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d mutex.** implem
362f0 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 entation, using
36300 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
36310 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 IG_GETMUTEX] opt
36320 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
36330 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f xMutexInit metho
36340 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 d defined by thi
36350 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 s structure is i
36360 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 nvoked as.** par
36370 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 t of system init
36380 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 ialization by th
36390 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
363a0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e lize() function.
363b0 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 .** ^The xMutexI
363c0 6e 69 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 nit routine is c
363d0 61 6c 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 alle by SQLite e
363e0 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 xactly once for
363f0 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 each.** effectiv
36400 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 e call to [sqlit
36410 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
36420 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 ..**.** ^The xMu
36430 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 texEnd method de
36440 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 fined by this st
36450 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b ructure is invok
36460 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 ed as.** part of
36470 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e system shutdown
36480 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
36490 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 shutdown() funct
364a0 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c ion. The.** impl
364b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
364c0 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 is method is exp
364d0 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 ected to release
364e0 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 all outstanding
364f0 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 .** resources ob
36500 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 tained by the mu
36510 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c tex methods impl
36520 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 ementation, espe
36530 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 cially.** those
36540 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 obtained by the
36550 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f xMutexInit metho
36560 64 2e 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 d. ^The xMutexE
36570 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 nd().** interfac
36580 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 e is invoked exa
36590 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 ctly once for ea
365a0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
365b0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e te3_shutdown()].
365c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d .**.** ^(The rem
365d0 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 aining seven met
365e0 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 hods defined by
365f0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28 this structure (
36600 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 xMutexAlloc,.**
36610 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 xMutexFree, xMut
36620 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 exEnter, xMutexT
36630 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c ry, xMutexLeave,
36640 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a xMutexHeld and.
36650 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 ** xMutexNotheld
36660 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 ) implement the
36670 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 following interf
36680 61 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65 aces (respective
36690 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ly):.**.** <ul>.
366a0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
366b0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
366c0 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
366d0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
366e0 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e ex_free()] </li>
366f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
36700 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
36710 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
36720 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
36730 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e tex_try()] </li>
36740 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
36750 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
36760 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
36770 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
36780 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 tex_held()] </li
36790 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
367a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 lite3_mutex_noth
367b0 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 eld()] </li>.**
367c0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 </ul>)^.**.** Th
367d0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
367e0 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75 e is that the pu
367f0 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 blic sqlite3_XXX
36800 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 functions enume
36810 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 rated.** above s
36820 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 ilently ignore a
36830 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 ny invocations t
36840 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 hat pass a NULL
36850 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a pointer instead.
36860 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 ** of a valid mu
36870 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 tex handle. The
36880 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
36890 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 of the methods d
368a0 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 efined.** by thi
368b0 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 s structure are
368c0 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 not required to
368d0 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 handle this case
368e0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a , the results.**
368f0 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 of passing a NU
36900 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 LL pointer inste
36910 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 ad of a valid mu
36920 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 tex handle are u
36930 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 ndefined.** (i.e
36940 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62 . it is acceptab
36950 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e le to provide an
36960 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
36970 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 that segfaults i
36980 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 f.** it is passe
36990 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 d a NULL pointer
369a0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 )..**.** The xMu
369b0 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 texInit() method
369c0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 must be threads
369d0 61 66 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 afe. ^It must b
369e0 65 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a e harmless to.**
369f0 20 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e invoke xMutexIn
36a00 69 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d it() mutiple tim
36a10 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 es within the sa
36a20 6d 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 me process and w
36a30 69 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 ithout.** interv
36a40 65 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 ening calls to x
36a50 4d 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 MutexEnd(). Sec
36a60 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
36a70 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 nt calls to.** x
36a80 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 MutexInit() must
36a90 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a be no-ops..**.*
36aa0 2a 20 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 * ^xMutexInit()
36ab0 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c must not use SQL
36ac0 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ite memory alloc
36ad0 61 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f ation ([sqlite3_
36ae0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 malloc()].** and
36af0 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 its associates)
36b00 2e 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 . ^Similarly, x
36b10 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 MutexAlloc() mus
36b20 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 t not use SQLite
36b30 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
36b40 61 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 ation for a stat
36b50 69 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 ic mutex. ^Howe
36b60 76 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 ver xMutexAlloc(
36b70 29 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 ) may use SQLite
36b80 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
36b90 61 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 ation for a fast
36ba0 20 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 or recursive mu
36bb0 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 tex..**.** ^SQLi
36bc0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
36bd0 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d he xMutexEnd() m
36be0 65 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 ethod when [sqli
36bf0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
36c00 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 is.** called, bu
36c10 74 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 t only if the pr
36c20 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 ior call to xMut
36c30 65 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 exInit returned
36c40 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 SQLITE_OK..** If
36c50 20 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c xMutexInit fail
36c60 73 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 s in any way, it
36c70 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 is expected to
36c80 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 clean up after i
36c90 74 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 tself.** prior t
36ca0 6f 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a o returning..*/.
36cb0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
36cc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
36cd0 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 hods sqlite3_mut
36ce0 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 ex_methods;.stru
36cf0 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
36d00 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 _methods {. int
36d10 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 (*xMutexInit)(v
36d20 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d oid);. int (*xM
36d30 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a utexEnd)(void);.
36d40 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 sqlite3_mutex
36d50 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 *(*xMutexAlloc)(
36d60 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 int);. void (*x
36d70 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 MutexFree)(sqlit
36d80 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 e3_mutex *);. v
36d90 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 oid (*xMutexEnte
36da0 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 r)(sqlite3_mutex
36db0 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 *);. int (*xMu
36dc0 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f texTry)(sqlite3_
36dd0 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 mutex *);. void
36de0 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 (*xMutexLeave)(
36df0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 sqlite3_mutex *)
36e00 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 ;. int (*xMutex
36e10 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 Held)(sqlite3_mu
36e20 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a tex *);. int (*
36e30 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 xMutexNotheld)(s
36e40 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b qlite3_mutex *);
36e50 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
36e60 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 REF: Mutex Verif
36e70 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 ication Routines
36e80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
36e90 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 e3_mutex_held()
36ea0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 and sqlite3_mute
36eb0 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 x_notheld() rout
36ec0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 ines.** are inte
36ed0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 nded for use ins
36ee0 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 ide assert() sta
36ef0 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 tements. ^The S
36f00 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 QLite core.** ne
36f10 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 ver uses these r
36f20 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 outines except i
36f30 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 nside an assert(
36f40 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f ) and applicatio
36f50 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 ns.** are advise
36f60 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 d to follow the
36f70 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 lead of the core
36f80 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 . ^The SQLite c
36f90 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 ore only.** prov
36fa0 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ides implementat
36fb0 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 ions for these r
36fc0 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 outines when it
36fd0 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 is compiled.** w
36fe0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 ith the SQLITE_D
36ff0 45 42 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 EBUG flag. ^Ext
37000 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c ernal mutex impl
37010 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 ementations.** a
37020 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 re only required
37030 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 to provide thes
37040 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 e routines if SQ
37050 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a LITE_DEBUG is.**
37060 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 defined and if
37070 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 NDEBUG is not de
37080 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
37090 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f ese routines sho
370a0 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 uld return true
370b0 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 if the mutex in
370c0 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a their argument.*
370d0 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 * is held or not
370e0 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 held, respectiv
370f0 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c ely, by the call
37100 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a ing thread..**.*
37110 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 * ^The implement
37120 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 ation is not req
37130 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 uired to provide
37140 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 d versions of th
37150 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ese.** routines
37160 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f that actually wo
37170 72 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 rk. If the imple
37180 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e mentation does n
37190 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 ot provide worki
371a0 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f ng.** versions o
371b0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
371c0 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c , it should at l
371d0 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 east provide stu
371e0 62 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a bs that always.*
371f0 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f * return true so
37200 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e that one does n
37210 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 ot get spurious
37220 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 assertion failur
37230 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 es..**.** ^If th
37240 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 e argument to sq
37250 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 lite3_mutex_held
37260 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
37270 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 nter then.** the
37280 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 routine should
37290 72 65 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 return 1. This
372a0 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 seems counter-i
372b0 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a ntuitive since.*
372c0 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 * clearly the mu
372d0 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 tex cannot be he
372e0 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f ld if it does no
372f0 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 t exist. But th
37300 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 e.** the reason
37310 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e the mutex does n
37320 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61 ot exist is beca
37330 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 use the build is
37340 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 not.** using mu
37350 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 texes. And we d
37360 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 o not want the a
37370 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 ssert() containi
37380 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 ng the.** call t
37390 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f o sqlite3_mutex_
373a0 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 held() to fail,
373b0 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 so a non-zero re
373c0 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 turn is.** the a
373d0 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 ppropriate thing
373e0 20 74 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 to do. ^The sq
373f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 lite3_mutex_noth
37400 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 eld().** interfa
37410 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 ce should also r
37420 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 eturn 1 when giv
37430 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 en a NULL pointe
37440 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 r..*/.#ifndef ND
37450 45 42 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 EBUG.int sqlite3
37460 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 _mutex_held(sqli
37470 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 te3_mutex*);.int
37480 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e sqlite3_mutex_n
37490 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d otheld(sqlite3_m
374a0 75 74 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a utex*);.#endif..
374b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
374c0 4d 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a Mutex Types.**.*
374d0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d * The [sqlite3_m
374e0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e utex_alloc()] in
374f0 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 terface takes a
37500 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a single argument.
37510 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 ** which is one
37520 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
37530 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a constants..**.*
37540 2a 20 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 * The set of sta
37550 74 69 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 tic mutexes may
37560 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 change from one
37570 53 51 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 SQLite release t
37580 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 o the.** next.
37590 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
375a0 74 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 t override the b
375b0 75 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f uilt-in mutex lo
375c0 67 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 gic must be.** p
375d0 72 65 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d repared to accom
375e0 6d 6f 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 modate additiona
375f0 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 l static mutexes
37600 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
37610 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 ITE_MUTEX_FAST
37620 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 0.#de
37630 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
37640 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 X_RECURSIVE
37650 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
37660 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
37670 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 _MASTER 2.#de
37680 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
37690 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 X_STATIC_MEM
376a0 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 3 /* sqlite3
376b0 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 _malloc() */.#de
376c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
376d0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 X_STATIC_MEM2
376e0 20 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 4 /* NOT USE
376f0 44 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c D */.#define SQL
37700 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
37710 5f 4f 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a _OPEN 4 /*
37720 20 73 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 sqlite3BtreeOpe
37730 6e 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 n() */.#define S
37740 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
37750 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 IC_PRNG 5
37760 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f /* sqlite3_rando
37770 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 m() */.#define S
37780 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
37790 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 IC_LRU 6
377a0 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 /* lru page list
377b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
377c0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
377d0 4c 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 LRU2 7 /*
377e0 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f lru page list */
377f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37800 3a 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6d : Retrieve the m
37810 75 74 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 utex for a datab
37820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
37830 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 *.** ^This inter
37840 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
37850 6f 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 ointer the [sqli
37860 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 te3_mutex] objec
37870 74 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 t that .** seria
37880 6c 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 lizes access to
37890 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
378a0 6e 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 nnection] given
378b0 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a in the argument.
378c0 2a 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 ** when the [thr
378d0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 eading mode] is
378e0 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e Serialized..** ^
378f0 49 66 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e If the [threadin
37900 67 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c g mode] is Singl
37910 65 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 e-thread or Mult
37920 69 2d 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 i-thread then th
37930 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 is.** routine re
37940 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
37950 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 nter..*/.sqlite3
37960 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f _mutex *sqlite3_
37970 64 62 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 db_mutex(sqlite3
37980 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
37990 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 REF: Low-Level C
379a0 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 ontrol Of Databa
379b0 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e se Files.**.** ^
379c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c The [sqlite3_fil
379d0 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 e_control()] int
379e0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 erface makes a d
379f0 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 irect call to th
37a00 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f e.** xFileContro
37a10 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 l method for the
37a20 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
37a30 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 hods] object ass
37a40 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 ociated.** with
37a50 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 a particular dat
37a60 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 abase identified
37a70 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 by the second a
37a80 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a rgument. ^The.**
37a90 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
37aa0 61 62 61 73 65 20 22 6d 61 69 6e 22 20 66 6f 72 abase "main" for
37ab0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 the main databa
37ac0 73 65 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72 se or "temp" for
37ad0 20 74 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74 the.** TEMP dat
37ae0 61 62 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61 abase, or the na
37af0 6d 65 20 74 68 61 74 20 61 70 70 65 61 72 73 20 me that appears
37b00 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 after the AS key
37b10 77 6f 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61 word for.** data
37b20 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 61 bases that are a
37b30 64 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b dded using the [
37b40 41 54 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d ATTACH] SQL comm
37b50 61 6e 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20 and..** ^A NULL
37b60 70 6f 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75 pointer can be u
37b70 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 sed in place of
37b80 22 6d 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20 "main" to refer
37b90 74 6f 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64 to the.** main d
37ba0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a atabase file..**
37bb0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 ^The third and
37bc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
37bd0 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e s to this routin
37be0 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 e.** are passed
37bf0 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 directly through
37c00 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 to the second a
37c10 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 nd third paramet
37c20 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 ers of.** the xF
37c30 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
37c40 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20 d. ^The return
37c50 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 value of the xFi
37c60 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 leControl.** met
37c70 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 hod becomes the
37c80 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
37c90 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a this routine..**
37ca0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f .** ^If the seco
37cb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 nd parameter (zD
37cc0 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 bName) does not
37cd0 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f match the name o
37ce0 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 f any.** open da
37cf0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 tabase file, the
37d00 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 n SQLITE_ERROR i
37d10 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 s returned. ^Th
37d20 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 is error.** code
37d30 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 is not remember
37d40 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 ed and will not
37d50 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b be recalled by [
37d60 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
37d70 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 )].** or [sqlite
37d80 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68 3_errmsg()]. Th
37d90 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 e underlying xFi
37da0 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
37db0 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 might.** also r
37dc0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 eturn SQLITE_ERR
37dd0 4f 52 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f OR. There is no
37de0 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 way to distingu
37df0 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 ish between.** a
37e00 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e n incorrect zDbN
37e10 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 ame and an SQLIT
37e20 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 E_ERROR return f
37e30 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 rom the underlyi
37e40 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 ng.** xFileContr
37e50 6f 6c 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a ol method..**.**
37e60 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 See also: [SQLI
37e70 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
37e80 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 TE].*/.int sqlit
37e90 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
37ea0 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 sqlite3*, const
37eb0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 char *zDbName, i
37ec0 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt op, void*);..
37ed0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
37ee0 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 Testing Interfac
37ef0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c e.**.** ^The sql
37f00 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f ite3_test_contro
37f10 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 l() interface is
37f20 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 used to read ou
37f30 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 t internal.** st
37f40 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e ate of SQLite an
37f50 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c d to inject faul
37f60 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 ts into SQLite f
37f70 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 or testing.** pu
37f80 72 70 6f 73 65 73 2e 20 20 5e 54 68 65 20 66 69 rposes. ^The fi
37f90 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
37fa0 20 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f an operation co
37fb0 64 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e de that determin
37fc0 65 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 es.** the number
37fd0 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f , meaning, and o
37fe0 70 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 peration of all
37ff0 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d subsequent param
38000 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 eters..**.** Thi
38010 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e s interface is n
38020 6f 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 ot for use by ap
38030 70 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 plications. It
38040 65 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a exists solely.**
38050 20 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 for verifying t
38060 68 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 he correct opera
38070 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 tion of the SQLi
38080 74 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 te library. Dep
38090 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 ending.** on how
380a0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
380b0 61 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c ary is compiled,
380c0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
380d0 6d 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e might not exist.
380e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 .**.** The detai
380f0 6c 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 ls of the operat
38100 69 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 ion codes, their
38110 20 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 meanings, the p
38120 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 arameters.** the
38130 79 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 y take, and what
38140 20 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c they do are all
38150 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
38160 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 ge without notic
38170 65 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 e..** Unlike mos
38180 74 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 t of the SQLite
38190 41 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 API, this functi
381a0 6f 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e on is not guaran
381b0 74 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 teed to.** opera
381c0 74 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 te consistently
381d0 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 from one release
381e0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f to the next..*/
381f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 .int sqlite3_tes
38200 74 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 t_control(int op
38210 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
38220 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 API3REF: Testing
38230 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 Interface Opera
38240 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a tion Codes.**.**
38250 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
38260 20 61 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f are the valid o
38270 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 peration code pa
38280 72 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a rameters used.**
38290 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
382a0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
382b0 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 e3_test_control(
382c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 )]..**.** These
382d0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74 parameters and t
382e0 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 heir meanings ar
382f0 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 e subject to cha
38300 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e nge.** without n
38310 6f 74 69 63 65 2e 20 20 54 68 65 73 65 20 76 61 otice. These va
38320 6c 75 65 73 20 61 72 65 20 66 6f 72 20 74 65 73 lues are for tes
38330 74 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e ting purposes on
38340 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 ly..** Applicati
38350 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 ons should not u
38360 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 se any of these
38370 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68 parameters or th
38380 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 e.** [sqlite3_te
38390 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e st_control()] in
383a0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 terface..*/.#def
383b0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
383c0 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 TRL_PRNG_SAVE
383d0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 5.#
383e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
383f0 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 STCTRL_PRNG_REST
38400 4f 52 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ORE
38410 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
38420 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 _TESTCTRL_PRNG_R
38430 45 53 45 54 20 20 20 20 20 20 20 20 20 20 20 20 ESET
38440 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 7.#define SQL
38450 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 ITE_TESTCTRL_BIT
38460 56 45 43 5f 54 45 53 54 20 20 20 20 20 20 20 20 VEC_TEST
38470 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
38480 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
38490 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 FAULT_INSTALL
384a0 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 9.#defi
384b0 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
384c0 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 RL_BENIGN_MALLOC
384d0 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 _HOOKS 10.#d
384e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
384f0 54 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 TCTRL_PENDING_BY
38500 54 45 20 20 20 20 20 20 20 20 20 20 20 20 31 31 TE 11
38510 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
38520 54 45 53 54 43 54 52 4c 5f 41 53 53 45 52 54 20 TESTCTRL_ASSERT
38530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
38540 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 12.#define SQLI
38550 54 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 41 TE_TESTCTRL_ALWA
38560 59 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 YS
38570 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 13.#define S
38580 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 52 QLITE_TESTCTRL_R
38590 45 53 45 52 56 45 20 20 20 20 20 20 20 20 20 20 ESERVE
385a0 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 14../*.**
385b0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74 CAPI3REF: SQLit
385c0 65 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73 e Runtime Status
385d0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
385e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 .**.** ^This int
385f0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
38600 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69 o retrieve runti
38610 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d me status inform
38620 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 ation.** about t
38630 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f he preformance o
38640 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70 f SQLite, and op
38650 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65 tionally to rese
38660 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67 t various.** hig
38670 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 5e hwater marks. ^
38680 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
38690 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 nt is an integer
386a0 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 code for.** the
386b0 20 73 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 specific parame
386c0 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 ter to measure.
386d0 20 5e 28 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e ^(Recognized in
386e0 74 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 teger codes.** a
386f0 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b re of the form [
38700 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 SQLITE_STATUS_ME
38710 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 MORY_USED | SQLI
38720 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 29 TE_STATUS_...].)
38730 5e 0a 2a 2a 20 5e 54 68 65 20 63 75 72 72 65 6e ^.** ^The curren
38740 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70 t value of the p
38750 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 75 arameter is retu
38760 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 72 rned into *pCurr
38770 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 68 69 67 ent..** ^The hig
38780 68 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 hest recorded va
38790 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 lue is returned
387a0 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 in *pHighwater.
387b0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 ^If the.** rese
387c0 74 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 tFlag is true, t
387d0 68 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 hen the highest
387e0 72 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 record value is
387f0 72 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a reset after.** *
38800 70 48 69 67 68 77 61 74 65 72 20 69 73 20 77 72 pHighwater is wr
38810 69 74 74 65 6e 2e 20 20 5e 28 53 6f 6d 65 20 70 itten. ^(Some p
38820 61 72 61 6d 65 74 65 72 73 20 64 6f 20 6e 6f 74 arameters do not
38830 20 72 65 63 6f 72 64 20 74 68 65 20 68 69 67 68 record the high
38840 65 73 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 est.** value. F
38850 6f 72 20 74 68 6f 73 65 20 70 61 72 61 6d 65 74 or those paramet
38860 65 72 73 0a 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 ers.** nothing i
38870 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a s written into *
38880 70 48 69 67 68 77 61 74 65 72 20 61 6e 64 20 74 pHighwater and t
38890 68 65 20 72 65 73 65 74 46 6c 61 67 20 69 73 20 he resetFlag is
388a0 69 67 6e 6f 72 65 64 2e 29 5e 0a 2a 2a 20 5e 28 ignored.)^.** ^(
388b0 4f 74 68 65 72 20 70 61 72 61 6d 65 74 65 72 73 Other parameters
388c0 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 74 68 65 record only the
388d0 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 highwater mark
388e0 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 75 72 72 and not the curr
388f0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 ent.** value. F
38900 6f 72 20 74 68 65 73 65 20 6c 61 74 74 65 72 20 or these latter
38910 70 61 72 61 6d 65 74 65 72 73 20 6e 6f 74 68 69 parameters nothi
38920 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e ng is written in
38930 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 29 5e 0a to *pCurrent.)^