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 7b 45 4e 44 7d 20 20 54 68 65 ject. {END} The
9190: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 y determine.** w
91a0: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d hat kind of perm
91b0: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 issions the xAcc
91c0: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f ess method is lo
91d0: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 oking for..** Wi
91e0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
91f0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 _EXISTS, the xAc
9200: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 cess method.** s
9210: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 imply checks whe
9220: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 ther the file ex
9230: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 ists..** With SQ
9240: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
9250: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 WRITE, the xAcce
9260: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
9270: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
9280: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 file is both rea
9290: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
92a0: 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 le..** With SQLI
92b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 TE_ACCESS_READ,
92c0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
92d0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 od.** checks whe
92e0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 ther the file is
92f0: 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 readable..*/.#d
9300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
9310: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a ESS_EXISTS 0.
9320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
9330: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 CCESS_READWRITE
9340: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
9350: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 _ACCESS_READ
9360: 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 2../*.** CAPI3
9370: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 REF: Initialize
9380: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
9390: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ry.**.** ^The sq
93a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
93b0: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 () routine initi
93c0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 alizes the.** SQ
93d0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e Lite library. ^
93e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 The sqlite3_shut
93f0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a down() routine.*
9400: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e * deallocates an
9410: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 y resources that
9420: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 were allocated
9430: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 by sqlite3_initi
9440: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 alize()..** Thes
9450: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 e routines are d
9460: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 esigned to aid i
9470: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 n process initia
9480: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 lization and.**
9490: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 shutdown on embe
94a0: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 dded systems. W
94b0: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 orkstation appli
94c0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a cations using.**
94d0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 SQLite normally
94e0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 do not need to
94f0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 invoke either of
9500: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
9510: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
9520: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9530: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 ize() is an "eff
9540: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 ective" call if
9550: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 it is.** the fir
9560: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
9570: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
9580: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 invoked during t
9590: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a he lifetime of.*
95a0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f * the process, o
95b0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 r if it is the f
95c0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 irst time sqlite
95d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
95e0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c s invoked.** fol
95f0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f lowing a call to
9600: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
9610: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 n(). ^(Only an
9620: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a effective call.*
9630: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 * of sqlite3_ini
9640: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 tialize() does a
9650: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ny initializatio
9660: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 n. All other ca
9670: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c lls.** are harml
9680: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a ess no-ops.)^.**
9690: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
96a0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
96b0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 is an "effectiv
96c0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 e" call if it is
96d0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 the first.** ca
96e0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
96f0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 utdown() since t
9700: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f he last sqlite3_
9710: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e initialize(). ^
9720: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 (Only.** an effe
9730: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 ctive call to sq
9740: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
9750: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 does any deinit
9760: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 ialization..** A
9770: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 ll other valid c
9780: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
9790: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 shutdown() are h
97a0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 armless no-ops.)
97b0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ^.**.** The sqli
97c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
97d0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 interface is th
97e0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 readsafe, but sq
97f0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
9800: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 .** is not. The
9810: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
9820: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 n() interface mu
9830: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 st only be calle
9840: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 d from a.** sing
9850: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 le thread. All
9860: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 open [database c
9870: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 onnections] must
9880: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 be closed and a
9890: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 ll.** other SQLi
98a0: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 te resources mus
98b0: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 t be deallocated
98c0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 prior to invoki
98d0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 ng.** sqlite3_sh
98e0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 utdown()..**.**
98f0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e Among other thin
9900: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 gs, ^sqlite3_ini
9910: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 tialize() will i
9920: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
9930: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d _os_init(). Sim
9940: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 ilarly, ^sqlite3
9950: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 _shutdown().** w
9960: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ill invoke sqlit
9970: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a e3_os_end()..**.
9980: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
9990: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
99a0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 tine returns [SQ
99b0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
99c0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 ess..** ^If for
99d0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c some reason, sql
99e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
99f0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 ) is unable to i
9a00: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 nitialize.** the
9a10: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 library (perhap
9a20: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 s it is unable t
9a30: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 o allocate a nee
9a40: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 ded resource suc
9a50: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 h.** as a mutex)
9a60: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b it returns an [
9a70: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 error code] othe
9a80: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f r than [SQLITE_O
9a90: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 K]..**.** ^The s
9aa0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9ab0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 e() routine is c
9ac0: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 alled internally
9ad0: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a by many other.*
9ae0: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 * SQLite interfa
9af0: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 ces so that an a
9b00: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c pplication usual
9b10: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ly does not need
9b20: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 to.** invoke sq
9b30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9b40: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f () directly. Fo
9b50: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 r example, [sqli
9b60: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 te3_open()].** c
9b70: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 alls sqlite3_ini
9b80: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 tialize() so the
9b90: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
9ba0: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 will be automati
9bb0: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c cally.** initial
9bc0: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 ized when [sqlit
9bd0: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 e3_open()] is ca
9be0: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e lled if it has n
9bf0: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 ot be initialize
9c00: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e d.** already. ^
9c10: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 However, if SQLi
9c20: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
9c30: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
9c40: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a OMIT_AUTOINIT].*
9c50: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f * compile-time o
9c60: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ption, then the
9c70: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 automatic calls
9c80: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 to sqlite3_initi
9c90: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f alize().** are o
9ca0: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 mitted and the a
9cb0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
9cc0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 call sqlite3_ini
9cd0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 tialize() direct
9ce0: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 ly.** prior to u
9cf0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 sing any other S
9d00: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
9d10: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f For maximum po
9d20: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 rtability,.** it
9d30: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
9d40: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
9d50: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 s always invoke
9d60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9d70: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 ze().** directly
9d80: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
9d90: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
9da0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 interface. Fut
9db0: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 ure releases.**
9dc0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 of SQLite may re
9dd0: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 quire this. In
9de0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
9df0: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 behavior exhibi
9e00: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 ted.** when SQLi
9e10: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
9e20: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 ith [SQLITE_OMIT
9e30: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 _AUTOINIT] might
9e40: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 become the.** d
9e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
9e60: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 in some future r
9e70: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
9e80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
9e90: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f te3_os_init() ro
9ea0: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 utine does opera
9eb0: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
9ec0: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ific.** initiali
9ed0: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 zation of the SQ
9ee0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 Lite library. T
9ef0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e he sqlite3_os_en
9f00: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 d().** routine u
9f10: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 ndoes the effect
9f20: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 of sqlite3_os_i
9f30: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 nit(). Typical
9f40: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d tasks.** perform
9f50: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 ed by these rout
9f60: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c ines include all
9f70: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c ocation or deall
9f80: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 ocation.** of st
9f90: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 atic resources,
9fa0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
9fb0: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c f global variabl
9fc0: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 es,.** setting u
9fd0: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c p a default [sql
9fe0: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 ite3_vfs] module
9ff0: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a , or setting up.
a000: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e ** a default con
a010: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 figuration using
a020: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
a030: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ()]..**.** The a
a040: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
a050: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 d never invoke e
a060: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 ither sqlite3_os
a070: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _init().** or sq
a080: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 lite3_os_end() d
a090: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 irectly. The ap
a0a0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
a0b0: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 only invoke.**
a0c0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
a0d0: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ze() and sqlite3
a0e0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 _shutdown(). Th
a0f0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 e sqlite3_os_ini
a100: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 t().** interface
a110: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d is called autom
a120: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 atically by sqli
a130: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
a140: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
a150: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c os_end() is call
a160: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 ed by sqlite3_sh
a170: 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f utdown(). Appro
a180: 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d priate.** implem
a190: 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 entations for sq
a1a0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
a1b0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 and sqlite3_os_e
a1c0: 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c nd().** are buil
a1d0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 t into SQLite wh
a1e0: 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 en it is compile
a1f0: 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 d for Unix, Wind
a200: 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a ows, or OS/2..**
a210: 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 When [custom bu
a220: 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 ilds | built for
a230: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 other platforms
a240: 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 ].** (using the
a250: 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 [SQLITE_OS_OTHER
a260: 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =1] compile-time
a270: 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 .** option) the
a280: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
a290: 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 supply a suitab
a2a0: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
a2b0: 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 n for.** sqlite3
a2c0: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
a2d0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e qlite3_os_end().
a2e0: 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e An application
a2f0: 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 -supplied.** imp
a300: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
a310: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a320: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 or sqlite3_os_e
a330: 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 nd().** must ret
a340: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
a350: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 on success and s
a360: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 ome other [error
a370: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 code] upon.** f
a380: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 ailure..*/.int s
a390: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
a3a0: 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c e(void);.int sql
a3b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f ite3_shutdown(vo
a3c0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 id);.int sqlite3
a3d0: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a _os_init(void);.
a3e0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 int sqlite3_os_e
a3f0: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a nd(void);../*.**
a400: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
a410: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 guring The SQLit
a420: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 20 45 58 50 e Library.** EXP
a430: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
a440: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
a450: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
a460: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 s used to make g
a470: 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 lobal configurat
a480: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
a490: 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 o SQLite in orde
a4a0: 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 r to tune SQLite
a4b0: 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 to the specific
a4c0: 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 needs of.** the
a4d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 application. T
a4e0: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 he default confi
a4f0: 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f guration is reco
a500: 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 mmended for most
a510: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 .** applications
a520: 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 and so this rou
a530: 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 tine is usually
a540: 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 not necessary.
a550: 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 It is.** provide
a560: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 d to support rar
a570: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 e applications w
a580: 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 ith unusual need
a590: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
a5a0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
a5b0: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 terface is not t
a5c0: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 hreadsafe. The
a5d0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d application.** m
a5e0: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 ust insure that
a5f0: 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 no other SQLite
a600: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 interfaces are i
a610: 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a nvoked by other.
a620: 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 ** threads while
a630: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
a640: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 ) is running. F
a650: 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 urthermore, sqli
a660: 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 te3_config().**
a670: 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f may only be invo
a680: 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 ked prior to lib
a690: 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 rary initializat
a6a0: 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ion using.** [sq
a6b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
a6c0: 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 ()] or after shu
a6d0: 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 tdown by [sqlite
a6e0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 3_shutdown()]..*
a6f0: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f * ^If sqlite3_co
a700: 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 nfig() is called
a710: 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f after [sqlite3_
a720: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e initialize()] an
a730: 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c d before.** [sql
a740: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
a750: 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 then it will re
a760: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 turn SQLITE_MISU
a770: 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 SE..** Note, how
a780: 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 ever, that ^sqli
a790: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e te3_config() can
a7a0: 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 be called as pa
a7b0: 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 rt of the.** imp
a7c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 lementation of a
a7d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
a7e0: 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f fined [sqlite3_o
a7f0: 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a s_init()]..**.**
a800: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
a810: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ent to sqlite3_c
a820: 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e onfig() is an in
a830: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 teger.** [SQLITE
a840: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
a850: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 READ | configura
a860: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 tion option] tha
a870: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 t determines.**
a880: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 what property of
a890: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 SQLite is to be
a8a0: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 configured. Su
a8b0: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
a8c0: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e ts.** vary depen
a8d0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c ding on the [SQL
a8e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
a8f0: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 ETHREAD | config
a900: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a uration option].
a910: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ** in the first
a920: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
a930: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 ^When a configur
a940: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
a950: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e set, sqlite3_con
a960: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 fig() returns [S
a970: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 QLITE_OK]..** ^I
a980: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 f the option is
a990: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 unknown or SQLit
a9a0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 e is unable to s
a9b0: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a et the option.**
a9c0: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 then this routi
a9d0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e ne returns a non
a9e0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
a9f0: 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 e]..*/.SQLITE_EX
aa00: 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
aa10: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e qlite3_config(in
aa20: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t, ...);../*.**
aa30: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
aa40: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ure database con
aa50: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 45 58 50 45 nections.** EXPE
aa60: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
aa70: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f he sqlite3_db_co
aa80: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
aa90: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 is used to make
aaa0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
aab0: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b * changes to a [
aac0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
aad0: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 ion]. The inter
aae0: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 face is similar
aaf0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
ab00: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 onfig()] except
ab10: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 that the changes
ab20: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 apply to a sing
ab30: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 le.** [database
ab40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 connection] (spe
ab50: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 cified in the fi
ab60: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 rst argument).
ab70: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 The.** sqlite3_d
ab80: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 b_config() inter
ab90: 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 face should only
aba0: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 be used immedia
abb0: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 tely after.** th
abc0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
abd0: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 ction is created
abe0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
abf0: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c open()],.** [sql
ac00: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
ac10: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e or [sqlite3_open
ac20: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 _v2()]. .**.**
ac30: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
ac40: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 ent to sqlite3_d
ac50: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e b_config(D,V,...
ac60: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e ) is the.** con
ac70: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 figuration verb
ac80: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 - an integer cod
ac90: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 e that indicates
aca0: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 what.** aspect
acb0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
acc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
acd0: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 being configured
ace0: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 ..** The only ch
acf0: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 oice for this va
ad00: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 lue is [SQLITE_D
ad10: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
ad20: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 E]..** New verbs
ad30: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 are likely to b
ad40: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
ad50: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
ad60: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f Lite..** Additio
ad70: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 nal arguments de
ad80: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 pend on the verb
ad90: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ..**.** ^Calls t
ada0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
adb0: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c fig() return SQL
adc0: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e ITE_OK if and on
add0: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c ly if.** the cal
ade0: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 l is considered
adf0: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a successful..**.*
ae00: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
ae10: 2a 2a 20 5b 48 31 34 32 30 33 5d 20 5b 48 31 34 ** [H14203] [H14
ae20: 32 30 36 5d 20 5b 48 31 34 32 30 39 5d 20 5b 48 206] [H14209] [H
ae30: 31 34 32 31 32 5d 20 5b 48 31 34 32 31 35 5d 0a 14212] [H14215].
ae40: 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 */.SQLITE_EXPERI
ae50: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
ae60: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c e3_db_config(sql
ae70: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e ite3*, int op, .
ae80: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
ae90: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
aea0: 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 ocation Routines
aeb0: 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 {H10155} <S2012
aec0: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
aed0: 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 AL.**.** An inst
aee0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
aef0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
af00: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 interface betwee
af10: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 n SQLite.** and
af20: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
af30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
af40: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ines..**.** This
af50: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 object is used
af60: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 in only one plac
af70: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 e in the SQLite
af80: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 interface..** A
af90: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
afa0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
afb0: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 bject is the arg
afc0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c ument to.** [sql
afd0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
afe0: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 hen the configur
aff0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a ation option is.
b000: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
b010: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 G_MALLOC] or [SQ
b020: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
b030: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 ALLOC]. .** By
b040: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 creating an inst
b050: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
b060: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 ect.** and passi
b070: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
b080: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 3_config]([SQLIT
b090: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
b0a0: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 ).** during conf
b0b0: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 iguration, an ap
b0c0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 plication can sp
b0d0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
b0e0: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 tive.** memory a
b0f0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
b100: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 tem for SQLite t
b110: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 o use for all of
b120: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 its.** dynamic
b130: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a memory needs..**
b140: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 .** Note that SQ
b150: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 Lite comes with
b160: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 several [built-i
b170: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
b180: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 ors].** that are
b190: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 perfectly adequ
b1a0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 ate for the over
b1b0: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 whelming majorit
b1c0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
b1d0: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 s.** and that th
b1e0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c is object is onl
b1f0: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 y useful to a ti
b200: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 ny minority of a
b210: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 pplications.** w
b220: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 ith specialized
b230: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
b240: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 n requirements.
b250: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a This object is.
b260: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 ** also used dur
b270: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 ing testing of S
b280: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
b290: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 o specify an alt
b2a0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
b2b0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 ry allocator tha
b2c0: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f t simulates memo
b2d0: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 ry out-of-memory
b2e0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a conditions in.*
b2f0: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 * order to verif
b300: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 y that SQLite re
b310: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c covers gracefull
b320: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 y from such.** c
b330: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a onditions..**.**
b340: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 The xMalloc and
b350: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d xFree methods m
b360: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 ust work like th
b370: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e e.** malloc() an
b380: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f d free() functio
b390: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ns from the stan
b3a0: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
b3b0: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 ** The xRealloc
b3c0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b method must work
b3d0: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 like realloc()
b3e0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
b3f0: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 d C library.** w
b400: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f ith the exceptio
b410: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65 n that if the se
b420: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
b430: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 xRealloc is zer
b440: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d o,.** xRealloc m
b450: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d ust be a no-op -
b460: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 it must not per
b470: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 form any allocat
b480: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f ion or.** deallo
b490: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 cation. ^SQLite
b4a0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
b4b0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
b4c0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c ment to.** xReal
b4d0: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 loc is always a
b4e0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
b4f0: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 y a prior call t
b500: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 o xRoundup..** A
b510: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77 nd so in cases w
b520: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c here xRoundup al
b530: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70 ways returns a p
b540: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a ositive number,.
b550: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 ** xRealloc can
b560: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 perform exactly
b570: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 as the standard
b580: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 library realloc(
b590: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 ) and.** still b
b5a0: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 e in compliance
b5b0: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66 with this specif
b5c0: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 ication..**.** x
b5d0: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 Size should retu
b5e0: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 rn the allocated
b5f0: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 size of a memor
b600: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
b610: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
b620: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 ned from xMalloc
b630: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 or xRealloc. T
b640: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
b650: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 e.** is always a
b660: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 t least as big a
b670: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 s the requested
b680: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 size but may be
b690: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 larger..**.** Th
b6a0: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f e xRoundup metho
b6b0: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 d returns what w
b6c0: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f ould be the allo
b6d0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a cated size of.**
b6e0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
b6f0: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 tion given a par
b700: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 ticular requeste
b710: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 d size. Most me
b720: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
b730: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f rs round up memo
b740: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 ry allocations a
b750: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e t least to the n
b760: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 ext multiple.**
b770: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f of 8. Some allo
b780: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
b790: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 to a larger mult
b7a0: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 iple or to a pow
b7b0: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 er of 2..** Ever
b7c0: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 y memory allocat
b7d0: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 ion request comi
b7e0: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 ng in through [s
b7f0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
b800: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
b810: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 realloc()] first
b820: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e calls xRoundup.
b830: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 If xRoundup re
b840: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 turns 0, .** tha
b850: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 t causes the cor
b860: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 responding memor
b870: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
b880: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fail..**.** The
b890: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 xInit method ini
b8a0: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d tializes the mem
b8b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 ory allocator.
b8c0: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a (For example,.**
b8d0: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 it might alloca
b8e0: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d te any require m
b8f0: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 utexes or initia
b900: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 lize internal da
b910: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 ta.** structures
b920: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e . The xShutdown
b930: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b method is invok
b940: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 ed (indirectly)
b950: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 by.** [sqlite3_s
b960: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 hutdown()] and s
b970: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 hould deallocate
b980: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 any resources a
b990: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 cquired.** by xI
b9a0: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 nit. The pAppDa
b9b0: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 ta pointer is us
b9c0: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 ed as the only p
b9d0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 arameter to.** x
b9e0: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f Init and xShutdo
b9f0: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 wn..**.** SQLite
ba00: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
ba10: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
ba20: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 MASTER] mutex wh
ba30: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a en it invokes.**
ba40: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
ba50: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 d, so the xInit
ba60: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 method need not
ba70: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 be threadsafe.
ba80: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e The.** xShutdown
ba90: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 method is only
baa0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c called from [sql
bab0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
bac0: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e so it does.** n
bad0: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 ot need to be th
bae0: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e readsafe either.
baf0: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 For all other
bb00: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a methods, SQLite.
bb10: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 ** holds the [SQ
bb20: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
bb30: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 C_MEM] mutex as
bb40: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b long as the.** [
bb50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
bb60: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 MSTATUS] configu
bb70: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
bb80: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 turned on (whic
bb90: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 h.** it is by de
bba0: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 fault) and so th
bbb0: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 e methods are au
bbc0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 tomatically seri
bbd0: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 alized..** Howev
bbe0: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 er, if [SQLITE_C
bbf0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
bc00: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 is disabled, th
bc10: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 en the other.**
bc20: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 methods must be
bc30: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c threadsafe or el
bc40: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 se make their ow
bc50: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 n arrangements f
bc60: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 or.** serializat
bc70: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ion..**.** SQLit
bc80: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 e will never inv
bc90: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 oke xInit() more
bca0: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f than once witho
bcb0: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e ut an intervenin
bcc0: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 g.** call to xSh
bcd0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 utdown()..*/.typ
bce0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
bcf0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
bd00: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
bd10: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
bd20: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
bd30: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c {. void *(*xMal
bd40: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 loc)(int);
bd50: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c /* Memory all
bd60: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e ocation function
bd70: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 */. void (*xFr
bd80: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ee)(void*);
bd90: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 /* Free a p
bda0: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
bdb0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 */. void *(*xRe
bdc0: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 alloc)(void*,int
bdd0: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e ); /* Resize an
bde0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
bdf0: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f int (*xSize)(vo
be00: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
be10: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 /* Return the si
be20: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 ze of an allocat
be30: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
be40: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 Roundup)(int);
be50: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 /* Round
be60: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 up request size
be70: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 to allocation s
be80: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ize */. int (*x
be90: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 Init)(void*);
bea0: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 /* Initi
beb0: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
bec0: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
bed0: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e void (*xShutdown
bee0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f )(void*); /
bef0: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 * Deinitialize t
bf00: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
bf10: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tor */. void *p
bf20: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
bf30: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d /* Argum
bf40: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 ent to xInit() a
bf50: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a nd xShutdown() *
bf60: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
bf70: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 3REF: Configurat
bf80: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 ion Options {H10
bf90: 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 160} <S20000>.**
bfa0: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
bfb0: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
bfc0: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
bfd0: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
bfe0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
bff0: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
c000: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
c010: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
c020: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
c030: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
c040: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
c050: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
c060: 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
c070: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
c080: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
c090: 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
c0a0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
c0b0: 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
c0c0: 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
c0d0: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
c0e0: 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
c0f0: 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
c100: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 ite3_config()] t
c110: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
c120: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 .** the call wor
c130: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ked. The [sqlit
c140: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 e3_config()] int
c150: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
c160: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
c170: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
c180: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
c190: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
c1a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
c1b0: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
c1c0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
c1d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
c1e0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c IG_SINGLETHREAD<
c1f0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
c200: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
c210: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
c220: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e n. ^This option
c230: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 sets the.** [th
c240: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
c250: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 Single-thread.
c260: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
c270: 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 it disables.**
c280: 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 all mutexing and
c290: 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 puts SQLite int
c2a0: 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 o a mode where i
c2b0: 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 t can only be us
c2c0: 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c ed.** by a singl
c2d0: 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 e thread. ^If
c2e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
c2f0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
c300: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
c310: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
c320: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
c330: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
c340: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
c350: 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 ossible to chang
c360: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
c370: 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 mode] from its
c380: 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 default.** value
c390: 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 of Single-threa
c3a0: 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 d and so [sqlite
c3b0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
c3c0: 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c return .** [SQL
c3d0: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 ITE_ERROR] if ca
c3e0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 lled with the SQ
c3f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
c400: 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 LETHREAD.** conf
c410: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
c420: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
c430: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
c440: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a ULTITHREAD</dt>.
c450: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
c460: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
c470: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e this option. ^
c480: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 This option sets
c490: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 the.** [threadi
c4a0: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 ng mode] to Mult
c4b0: 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 i-thread. In ot
c4c0: 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 her words, it di
c4d0: 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 sables.** mutexi
c4e0: 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 ng on [database
c4f0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 connection] and
c500: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
c510: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a ent] objects..**
c520: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
c530: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
c540: 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 for serializing
c550: 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 access to.** [da
c560: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
c570: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 ns] and [prepare
c580: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 d statements].
c590: 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 But other mutexe
c5a0: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 s.** are enabled
c5b0: 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 so that SQLite
c5c0: 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 will be safe to
c5d0: 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 use in a multi-t
c5e0: 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 hreaded.** envir
c5f0: 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 onment as long a
c600: 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 s no two threads
c610: 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 attempt to use
c620: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 the same.** [dat
c630: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
c640: 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 ] at the same ti
c650: 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 me. ^If SQLite
c660: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
c670: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
c680: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
c690: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
c6a0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
c6b0: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
c6c0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
c6d0: 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 to set the Mult
c6e0: 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 i-thread [thread
c6f0: 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a ing mode] and.**
c700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
c710: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ()] will return
c720: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
c730: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 f called with th
c740: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 e.** SQLITE_CONF
c750: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 IG_MULTITHREAD c
c760: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
c770: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
c780: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
c790: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 G_SERIALIZED</dt
c7a0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
c7b0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
c7c0: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
c7d0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
c7e0: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
c7f0: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 ding mode] to Se
c800: 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 rialized. In oth
c810: 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f er words, this o
c820: 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a ption enables.**
c830: 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 all mutexes inc
c840: 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 luding the recur
c850: 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 sive.** mutexes
c860: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
c870: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
c880: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
c890: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e ] objects..** In
c8a0: 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 this mode (whic
c8b0: 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 h is the default
c8c0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
c8d0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
c8e0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
c8f0: 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 AFE=1]) the SQLi
c900: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 te library will
c910: 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 itself serialize
c920: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 access.** to [d
c930: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
c940: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
c950: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 ed statements] s
c960: 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 o that the.** ap
c970: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 plication is fre
c980: 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d e to use the sam
c990: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
c9a0: 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a ection] or the.*
c9b0: 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 * same [prepared
c9c0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 statement] in d
c9d0: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 ifferent threads
c9e0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
c9f0: 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 e..** ^If SQLite
ca00: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
ca10: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
ca20: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
ca30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
ca40: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
ca50: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
ca60: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
ca70: 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 e to set the Ser
ca80: 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
ca90: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
caa0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
cab0: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
cac0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
cad0: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
cae0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
caf0: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e G_SERIALIZED con
cb00: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
cb10: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
cb20: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
cb30: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
cb40: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
cb50: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
cb60: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
cb70: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
cb80: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
cb90: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
cba0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
cbb0: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 cture. The argu
cbc0: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a ment specifies.*
cbd0: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f * alternative lo
cbe0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
cbf0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
cc00: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e es to be used in
cc10: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 place of.** the
cc20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
cc30: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c on routines buil
cc40: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e t into SQLite.)^
cc50: 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a ^SQLite makes.*
cc60: 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 * its own privat
cc70: 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f e copy of the co
cc80: 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
cc90: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
cca0: 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 s] structure.**
ccb0: 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 before the [sqli
ccc0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 te3_config()] ca
ccd0: 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e ll returns.</dd>
cce0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
ccf0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
cd00: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OC</dt>.** <dd>
cd10: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^(This option ta
cd20: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
cd30: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
cd40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
cd50: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
cd60: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
cd70: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
cd80: 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 e. The [sqlite3
cd90: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a _mem_methods].**
cda0: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
cdb0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
cdc0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
cdd0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
cde0: 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a n routines.)^.**
cdf0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
ce00: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
ce10: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
ce20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
ce30: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
ce40: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 ith a wrapper th
ce50: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d at simulations m
ce60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
ce70: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 failure or.** t
ce80: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 racks memory usa
ce90: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ge, for example.
cea0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
ceb0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
cec0: 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a EMSTATUS</dt>.**
ced0: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
cee0: 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 on takes single
cef0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
cf00: 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 int, interprete
cf10: 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 d as a .** boole
cf20: 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 an, which enable
cf30: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
cf40: 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 e collection of
cf50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
cf60: 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 n .** statistics
cf70: 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 . ^(When memory
cf80: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
cf90: 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c stics are disabl
cfa0: 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c ed, the .** foll
cfb0: 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 owing SQLite int
cfc0: 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e erfaces become n
cfd0: 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a on-operational:.
cfe0: 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c ** <ul>.** <
cff0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d li> [sqlite3_mem
d000: 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 ory_used()].**
d010: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
d020: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
d030: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
d040: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
d050: 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c limit()].** <l
d060: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 i> [sqlite3_stat
d070: 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e us()].** </ul>
d080: 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c )^.** ^Memory al
d090: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 location statist
d0a0: 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 ics are enabled
d0b0: 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 by default unles
d0c0: 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 s SQLite is.** c
d0d0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
d0e0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d LITE_DEFAULT_MEM
d0f0: 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 STATUS]=0 in whi
d100: 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a ch case memory.*
d110: 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 * allocation sta
d120: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 tistics are disa
d130: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
d140: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
d150: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
d160: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a G_SCRATCH</dt>.*
d170: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
d180: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
d190: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
d1a0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
d1b0: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 can use for.**
d1c0: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 scratch memory.
d1d0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 There are three
d1e0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 arguments: A p
d1f0: 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 ointer an 8-byte
d200: 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f .** aligned memo
d210: 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 ry buffer from w
d220: 68 69 63 68 20 74 68 65 20 73 63 72 61 63 68 20 hich the scrach
d230: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c allocations will
d240: 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 be.** drawn, th
d250: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 e size of each s
d260: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f cratch allocatio
d270: 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 n (sz),.** and t
d280: 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
d290: 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c r of scratch all
d2a0: 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 ocations (N). T
d2b0: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e he sz.** argumen
d2c0: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 t must be a mult
d2d0: 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20 iple of 16. The
d2e0: 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f sz parameter sho
d2f0: 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 79 74 uld be a few byt
d300: 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 es.** larger tha
d310: 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 63 72 n the actual scr
d320: 61 74 63 68 20 73 70 61 63 65 20 72 65 71 75 69 atch space requi
d330: 72 65 64 20 64 75 65 20 74 6f 20 69 6e 74 65 72 red due to inter
d340: 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a nal overhead..**
d350: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
d360: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f ent must be a po
d370: 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 inter to an 8-by
d380: 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 te aligned buffe
d390: 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 r.** of at least
d3a0: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d sz*N bytes of m
d3b0: 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 emory..** ^SQLit
d3c0: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f e will use no mo
d3d0: 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 re than one scra
d3e0: 74 63 68 20 62 75 66 66 65 72 20 70 65 72 20 74 tch buffer per t
d3f0: 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 hread. So.** N
d400: 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f should be set to
d410: 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 the expected ma
d420: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
d430: 74 68 72 65 61 64 73 2e 20 20 5e 53 51 4c 69 74 threads. ^SQLit
d440: 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 e will.** never
d450: 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63 require a scratc
d460: 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 h buffer that is
d470: 20 6d 6f 72 65 20 74 68 61 6e 20 36 20 74 69 6d more than 6 tim
d480: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a es the database.
d490: 2a 2a 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 ** page size. ^I
d4a0: 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e f SQLite needs n
d4b0: 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 eeds additional
d4c0: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 scratch memory b
d4d0: 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74 20 69 eyond .** what i
d4e0: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 s provided by th
d4f0: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e is configuration
d500: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a option, then .*
d510: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
d520: 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 c()] will be use
d530: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 d to obtain the
d540: 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f memory needed.</
d550: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
d560: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
d570: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 CACHE</dt>.** <d
d580: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
d590: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
d5a0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
d5b0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e that SQLite can
d5c0: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 use for.** the
d5d0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 database page ca
d5e0: 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 che with the def
d5f0: 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 ault page cache
d600: 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 implemenation.
d610: 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 .** This configu
d620: 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f ration should no
d630: 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 t be used if an
d640: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
d650: 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 ne page.** cache
d660: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
d670: 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 is loaded using
d680: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
d690: 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e G_PCACHE option.
d6a0: 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 .** There are th
d6b0: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ree arguments to
d6c0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 this option: A
d6d0: 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 pointer to 8-byt
d6e0: 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d e aligned.** mem
d6f0: 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 ory, the size of
d700: 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 each page buffe
d710: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 r (sz), and the
d720: 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
d730: 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 (N)..** The sz a
d740: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 rgument should b
d750: 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 e the size of th
d760: 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 e largest databa
d770: 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f se page.** (a po
d780: 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 wer of two betwe
d790: 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 en 512 and 32768
d7a0: 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 ) plus a little
d7b0: 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a extra for each.*
d7c0: 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 * page header.
d7d0: 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 ^The page header
d7e0: 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 size is 20 to 4
d7f0: 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 0 bytes dependin
d800: 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 g on.** the host
d810: 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 architecture.
d820: 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c ^It is harmless,
d830: 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 apart from the
d840: 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a wasted memory,.*
d850: 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c * to make sz a l
d860: 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e ittle too large.
d870: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 The first.** a
d880: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 rgument should p
d890: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 oint to an alloc
d8a0: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 ation of at leas
d8b0: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
d8c0: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 memory..** ^SQLi
d8d0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 te will use the
d8e0: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 memory provided
d8f0: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 by the first arg
d900: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 ument to satisfy
d910: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e its.** memory n
d920: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 eeds for the fir
d930: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 st N pages that
d940: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 it adds to cache
d950: 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 . ^If additiona
d960: 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 l.** page cache
d970: 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 memory is needed
d980: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 beyond what is
d990: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 provided by this
d9a0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a option, then.**
d9b0: 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 SQLite goes to
d9c0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
d9d0: 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 )] for the addit
d9e0: 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 ional storage sp
d9f0: 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 ace..** ^The imp
da00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 lementation migh
da10: 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 t use one or mor
da20: 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 e of the N buffe
da30: 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d rs to hold .** m
da40: 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 emory accounting
da50: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 information. Th
da60: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 e pointer in the
da70: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
da80: 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e must.** be align
da90: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
daa0: 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 boundary or subs
dab0: 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
dac0: 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c of SQLite.** wil
dad0: 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
dae0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
daf0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
db00: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e P</dt>.** <dd> ^
db10: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 This option spec
db20: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
db30: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 emory buffer tha
db40: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 t SQLite will us
db50: 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 e.** for all of
db60: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f its dynamic memo
db70: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
db80: 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 eds beyond those
db90: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 provided.** for
dba0: 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
dbb0: 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 IG_SCRATCH] and
dbc0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
dbd0: 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 AGECACHE]..** Th
dbe0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
dbf0: 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 guments: An 8-by
dc00: 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 te aligned point
dc10: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 er to the memory
dc20: 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 ,.** the number
dc30: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
dc40: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 memory buffer, a
dc50: 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 nd the minimum a
dc60: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a llocation size..
dc70: 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 ** ^If the first
dc80: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 pointer (the me
dc90: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 mory pointer) is
dca0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 NULL, then SQLi
dcb0: 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f te reverts.** to
dcc0: 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 using its defau
dcd0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
dce0: 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 tor (the system
dcf0: 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 malloc() impleme
dd00: 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 ntation),.** und
dd10: 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 oing any prior i
dd20: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 nvocation of [SQ
dd30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
dd40: 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a OC]. ^If the.**
dd50: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 memory pointer
dd60: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 is not NULL and
dd70: 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 either [SQLITE_E
dd80: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f NABLE_MEMSYS3] o
dd90: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 r.** [SQLITE_ENA
dda0: 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 BLE_MEMSYS5] are
ddb0: 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 defined, then t
ddc0: 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d he alternative m
ddd0: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
dde0: 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f or is engaged to
ddf0: 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 handle all of S
de00: 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c QLites memory al
de10: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a location needs..
de20: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 ** The first poi
de30: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
de40: 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 pointer) must b
de50: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
de60: 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 8-byte.** bounda
de70: 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 ry or subsequent
de80: 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c behavior of SQL
de90: 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 ite will be unde
dea0: 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a fined.</dd>.**.*
deb0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
dec0: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a FIG_MUTEX</dt>.*
ded0: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 * <dd> ^(This op
dee0: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
def0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
df00: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ch is a pointer
df10: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 to an.** instanc
df20: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
df30: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
df40: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
df50: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 argument specif
df60: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 ies.** alternati
df70: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 ve low-level mut
df80: 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 ex routines to b
df90: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a e used in place.
dfa0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 ** the mutex rou
dfb0: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f tines built into
dfc0: 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c SQLite.)^ ^SQL
dfd0: 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
dfe0: 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 of the.** conte
dff0: 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 nt of the [sqlit
e000: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
e010: 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f ] structure befo
e020: 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a re the call to.*
e030: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
e040: 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 g()] returns. ^I
e050: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
e060: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
e070: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
e080: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
e090: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
e0a0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
e0b0: 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 hen.** the entir
e0c0: 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 e mutexing subsy
e0d0: 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 stem is omitted
e0e0: 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 from the build a
e0f0: 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 nd hence calls t
e100: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
e110: 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 nfig()] with the
e120: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
e130: 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 UTEX configurati
e140: 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a on option will.*
e150: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
e160: 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a _ERROR].</dd>.**
e170: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
e180: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f ONFIG_GETMUTEX</
e190: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
e1a0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
e1b0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
e1c0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
e1d0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
e1e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
e1f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
e200: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
e210: 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 The.** [sqlite
e220: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
e230: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 .** structure is
e240: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
e250: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
e260: 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 ed mutex routine
e270: 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 s.)^.** This opt
e280: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
e290: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 to overload the
e2a0: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c default mutex al
e2b0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 location.** rout
e2c0: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 ines with a wrap
e2d0: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 per used to trac
e2e0: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f k mutex usage fo
e2f0: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a r performance.**
e300: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 profiling or te
e310: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 sting, for examp
e320: 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 le. ^If SQLite
e330: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
e340: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
e350: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
e360: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
e370: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
e380: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 option then.** t
e390: 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 he entire mutexi
e3a0: 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 ng subsystem is
e3b0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 omitted from the
e3c0: 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 build and hence
e3d0: 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
e3e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
e3f0: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
e400: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 CONFIG_GETMUTEX
e410: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
e420: 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 tion will.** ret
e430: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
e440: 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c R].</dd>.**.** <
e450: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
e460: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a _LOOKASIDE</dt>.
e470: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
e480: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 ption takes two
e490: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
e4a0: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 etermine the def
e4b0: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 ault.** memory a
e4c0: 6c 6c 6f 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 llocation lookas
e4d0: 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ide optimization
e4e0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 . The first arg
e4f0: 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 ument is the.**
e500: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f size of each loo
e510: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c kaside buffer sl
e520: 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ot and the secon
e530: 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 d is the number
e540: 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f of.** slots allo
e550: 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 cated to each da
e560: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
e570: 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 n.)^ ^(This opt
e580: 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 ion sets the.**
e590: 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c <i>default</i> l
e5a0: 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 ookaside size. T
e5b0: 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e he [SQLITE_DBCON
e5c0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a FIG_LOOKASIDE].*
e5d0: 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 * verb to [sqlit
e5e0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
e5f0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 can be used to c
e600: 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 hange the lookas
e610: 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 ide.** configura
e620: 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 tion on individu
e630: 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 al connections.)
e640: 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 ^ </dd>.**.** <d
e650: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
e660: 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c PCACHE</dt>.** <
e670: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
e680: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
e690: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
e6a0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a is a pointer to.
e6b0: 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 ** an [sqlite3_p
e6c0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f cache_methods] o
e6d0: 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a bject. This obj
e6e0: 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 ect specifies th
e6f0: 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 e interface.** t
e700: 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 o a custom page
e710: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
e720: 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 tion.)^ ^SQLite
e730: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
e740: 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 the.** object a
e750: 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 nd uses it for p
e760: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 age cache memory
e770: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 allocations.</d
e780: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
e790: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
e7a0: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ACHE</dt>.** <dd
e7b0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
e7c0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
e7d0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
e7e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
e7f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 .** [sqlite3_pca
e800: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a che_methods] obj
e810: 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 ect. SQLite cop
e820: 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 ies of the curre
e830: 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 nt.** page cache
e840: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
e850: 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 into that object
e860: 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
e870: 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
e880: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
e890: 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 INGLETHREAD 1
e8a0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
e8b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
e8c0: 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 MULTITHREAD 2
e8d0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
e8e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
e8f0: 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 _SERIALIZED 3
e900: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
e910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
e920: 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 G_MALLOC
e930: 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 4 /* sqlite3_me
e940: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
e950: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
e960: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 FIG_GETMALLOC
e970: 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
e980: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
e990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
e9a0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 ONFIG_SCRATCH
e9b0: 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 6 /* void*,
e9c0: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a int sz, int N *
e9d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
e9e0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
e9f0: 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 E 7 /* void
ea00: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
ea10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
ea20: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 TE_CONFIG_HEAP
ea30: 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 8 /* vo
ea40: 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 id*, int nByte,
ea50: 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 int min */.#defi
ea60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
ea70: 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 _MEMSTATUS 9
ea80: 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a /* boolean */.
ea90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
eaa0: 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 ONFIG_MUTEX
eab0: 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 10 /* sqlite
eac0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 3_mutex_methods*
ead0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
eae0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
eaf0: 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 EX 11 /* sq
eb00: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
eb10: 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 ods* */./* previ
eb20: 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e ously SQLITE_CON
eb30: 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 FIG_CHUNKALLOC 1
eb40: 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 2 which is now u
eb50: 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 nused. */ .#defi
eb60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
eb70: 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 _LOOKASIDE 13
eb80: 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a /* int int */.
eb90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
eba0: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 ONFIG_PCACHE
ebb0: 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 14 /* sqlite
ebc0: 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
ebd0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
ebe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
ebf0: 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 ACHE 15 /* s
ec00: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
ec10: 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a thods* */../*.**
ec20: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
ec30: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 guration Options
ec40: 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 {H10170} <S2000
ec50: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
ec60: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 AL.**.** These c
ec70: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
ec80: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
ec90: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
eca0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
ecb0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
ecc0: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
ecd0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
ece0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
ecf0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
ed00: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
ed10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
ed20: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
ed30: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
ed40: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
ed50: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
ed60: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
ed70: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
ed80: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
ed90: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
eda0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
edb0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 from [sqlite3_db
edc0: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 _config()] to ma
edd0: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 ke sure that.**
ede0: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e the call worked.
edf0: 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ^The [sqlite3_
ee00: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
ee10: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
ee20: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
ee30: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
ee40: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
ee50: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
ee60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
ee70: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
ee80: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
ee90: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
eea0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
eeb0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
eec0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 s option takes t
eed0: 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 hree additional
eee0: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
eef0: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a etermine the .**
ef00: 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f [lookaside memo
ef10: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f ry allocator] co
ef20: 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 nfiguration for
ef30: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
ef40: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 nnection]..** ^T
ef50: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
ef60: 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 t (the third par
ef70: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
ef80: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
ef90: 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 is a.** pointer
efa0: 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66 to an memory buf
efb0: 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c fer to use for l
efc0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e ookaside memory.
efd0: 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
efe0: 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 rgument after th
eff0: 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
f000: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 G_LOOKASIDE verb
f010: 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 .** may be NULL
f020: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 in which case SQ
f030: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 Lite will alloca
f040: 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 te the.** lookas
f050: 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c ide buffer itsel
f060: 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 f using [sqlite3
f070: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 _malloc()]. ^The
f080: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
f090: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 is the.** size
f0a0: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 of each lookasid
f0b0: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 e buffer slot.
f0c0: 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d ^The third argum
f0d0: 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ent is the numbe
f0e0: 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 r of.** slots.
f0f0: 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
f100: 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 buffer in the fi
f110: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
f120: 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 t be greater tha
f130: 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f n.** or equal to
f140: 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 the product of
f150: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
f160: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 hird arguments.
f170: 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d The buffer.** m
f180: 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 ust be aligned t
f190: 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e o an 8-byte boun
f1a0: 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 dary. ^If the s
f1b0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
f1c0: 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f o.** SQLITE_DBCO
f1d0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 NFIG_LOOKASIDE i
f1e0: 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 s not a multiple
f1f0: 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 of 8, it is int
f200: 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 ernally.** round
f210: 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e ed down to the n
f220: 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d ext smaller.** m
f230: 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 53 ultiple of 8. S
f240: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
f250: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
f260: 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f E]</dd>.**.** </
f270: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
f280: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
f290: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31 OOKASIDE 1001
f2a0: 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 /* void* int i
f2b0: 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt */.../*.** CA
f2c0: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f PI3REF: Enable O
f2d0: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 r Disable Extend
f2e0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a ed Result Codes.
f2f0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
f300: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
f310: 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 lt_codes() routi
f320: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ne enables or di
f330: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 sables the.** [e
f340: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
f350: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 odes] feature of
f360: 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 SQLite. ^The ex
f370: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a tended result.**
f380: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 codes are disab
f390: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 led by default f
f3a0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f or historical co
f3b0: 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a mpatibility..*/.
f3c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
f3d0: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
f3e0: 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
f3f0: 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
f400: 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e API3REF: Last In
f410: 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a sert Rowid.**.**
f420: 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 ^Each entry in
f430: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 an SQLite table
f440: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d has a unique 64-
f450: 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e bit signed.** in
f460: 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 teger key called
f470: 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 the [ROWID | "r
f480: 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 owid"]. ^The row
f490: 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 id is always ava
f4a0: 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 ilable.** as an
f4b0: 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d undeclared colum
f4c0: 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f n named ROWID, O
f4d0: 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 ID, or _ROWID_ a
f4e0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a s long as those.
f4f0: 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 ** names are not
f500: 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 also used by ex
f510: 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
f520: 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a d columns. ^If.*
f530: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 * the table has
f540: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 a column of type
f550: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 [INTEGER PRIMAR
f560: 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 Y KEY] then that
f570: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e column.** is an
f580: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 other alias for
f590: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a the rowid..**.**
f5a0: 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 ^This routine r
f5b0: 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 eturns the [rowi
f5c0: 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 d] of the most r
f5d0: 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 ecent.** success
f5e0: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 ful [INSERT] int
f5f0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 o the database f
f600: 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 rom the [databas
f610: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
f620: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
f630: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20 gument. ^If no
f640: 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
f650: 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 RT]s.** have eve
f660: 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 r occurred on th
f670: 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e at database conn
f680: 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 ection, zero is
f690: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
f6a0: 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d ^(If an [INSERT]
f6b0: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
f6c0: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 trigger, then t
f6d0: 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 he [rowid] of th
f6e0: 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f e inserted.** ro
f6f0: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 w is returned by
f700: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 this routine as
f710: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 long as the tri
f720: 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e gger is running.
f730: 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 .** But once the
f740: 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 trigger termina
f750: 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 tes, the value r
f760: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 eturned by this
f770: 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 routine.** rever
f780: 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 ts to the last v
f790: 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 alue inserted be
f7a0: 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 fore the trigger
f7b0: 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 fired.)^.**.**
f7c0: 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 ^An [INSERT] tha
f7d0: 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 t fails due to a
f7e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
f7f0: 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a ation is not a.*
f800: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e * successful [IN
f810: 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e SERT] and does n
f820: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
f830: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
f840: 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e this.** routine.
f850: 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f ^Thus INSERT O
f860: 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f R FAIL, INSERT O
f870: 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 R IGNORE, INSERT
f880: 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a OR ROLLBACK,.**
f890: 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 and INSERT OR A
f8a0: 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 BORT make no cha
f8b0: 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 nges to the retu
f8c0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
f8d0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e .** routine when
f8e0: 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e their insertion
f8f0: 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 fails. ^(When
f900: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 INSERT OR REPLAC
f910: 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 E.** encounters
f920: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
f930: 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 lation, it does
f940: 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a not fail. The.*
f950: 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 * INSERT continu
f960: 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e es to completion
f970: 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 after deleting
f980: 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 rows that caused
f990: 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 .** the constrai
f9a0: 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e nt problem so IN
f9b0: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 SERT OR REPLACE
f9c0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e will always chan
f9d0: 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e ge.** the return
f9e0: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 value of this i
f9f0: 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a nterface.)^.**.*
fa00: 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f * ^For the purpo
fa10: 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ses of this rout
fa20: 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d ine, an [INSERT]
fa30: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 is considered t
fa40: 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 o.** be successf
fa50: 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 ul even if it is
fa60: 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f subsequently ro
fa70: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a lled back..**.**
fa80: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
fa90: 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 s accessible to
faa0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 SQL statements v
fab0: 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f ia the.** [last_
fac0: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 insert_rowid() S
fad0: 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
fae0: 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
faf0: 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d e thread perform
fb00: 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d s a new [INSERT]
fb10: 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 on the same.**
fb20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
fb30: 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 ion while the [s
fb40: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
fb50: 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 rt_rowid()].** f
fb60: 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
fb70: 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e ng and thus chan
fb80: 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 ges the last ins
fb90: 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 ert [rowid],.**
fba0: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 then the value r
fbb0: 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
fbc0: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
fbd0: 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 rowid()] is.** u
fbe0: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
fbf0: 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c might not equal
fc00: 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 either the old
fc10: 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 or the new.** la
fc20: 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 st insert [rowid
fc30: 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e ]..*/.sqlite3_in
fc40: 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 t64 sqlite3_last
fc50: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 _insert_rowid(sq
fc60: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
fc70: 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 CAPI3REF: Count
fc80: 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f The Number Of Ro
fc90: 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a ws Modified.**.*
fca0: 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
fcb0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
fcc0: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 ber of database
fcd0: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 rows that were c
fce0: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 hanged.** or ins
fcf0: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 erted or deleted
fd00: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 by the most rec
fd10: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 ently completed
fd20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL statement.**
fd30: 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 on the [databas
fd40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
fd50: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 ecified by the f
fd60: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a irst parameter..
fd70: 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 ** ^(Only change
fd80: 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 s that are direc
fd90: 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 tly specified by
fda0: 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b the [INSERT], [
fdb0: 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b UPDATE],.** or [
fdc0: 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e DELETE] statemen
fdd0: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 t are counted.
fde0: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 Auxiliary change
fdf0: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 s caused by.** t
fe00: 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 riggers or [fore
fe10: 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d ign key actions]
fe20: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
fe30: 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b .)^ Use the.** [
fe40: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
fe50: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f anges()] functio
fe60: 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f n to find the to
fe70: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 tal number of ch
fe80: 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 anges.** includi
fe90: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ng changes cause
fea0: 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e d by triggers an
feb0: 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 d foreign key ac
fec0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 tions..**.** ^Ch
fed0: 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 anges to a view
fee0: 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 that are simulat
fef0: 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 ed by an [INSTEA
ff00: 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a D OF trigger].**
ff10: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
ff20: 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 . Only real tab
ff30: 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 le changes are c
ff40: 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ounted..**.** ^(
ff50: 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 A "row change" i
ff60: 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 s a change to a
ff70: 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 single row of a
ff80: 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 single table.**
ff90: 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 caused by an INS
ffa0: 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 ERT, DELETE, or
ffb0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 UPDATE statement
ffc0: 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 . Rows that.**
ffd0: 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 are changed as s
ffe0: 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b ide effects of [
fff0: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 REPLACE] constra
10000 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a int resolution,.
10010 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f ** rollback, ABO
10020 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b RT processing, [
10030 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 DROP TABLE], or
10040 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 by any other.**
10050 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f mechanisms do no
10060 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 t count as direc
10070 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e t row changes.)^
10080 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 .**.** A "trigge
10090 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 r context" is a
100a0 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 scope of executi
100b0 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 on that begins a
100c0 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 nd.** ends with
100d0 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 the script of a
100e0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 [CREATE TRIGGER
100f0 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 | trigger]. .**
10100 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 Most SQL stateme
10110 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 nts are.** evalu
10120 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 ated outside of
10130 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 any trigger. Th
10140 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c is is the "top l
10150 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 evel".** trigger
10160 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 context. If a
10170 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 trigger fires fr
10180 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c om the top level
10190 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 , a.** new trigg
101a0 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e er context is en
101b0 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 tered for the du
101c0 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f ration of that o
101d0 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 ne.** trigger.
101e0 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 Subtriggers crea
101f0 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 te subcontexts f
10200 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f or their duratio
10210 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e n..**.** ^Callin
10220 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 g [sqlite3_exec(
10230 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 )] or [sqlite3_s
10240 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 tep()] recursive
10250 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 ly does.** not c
10260 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 reate a new trig
10270 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a ger context..**.
10280 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
10290 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
102a0 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 mber of direct r
102b0 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 ow changes in th
102c0 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 e.** most recent
102d0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
102e0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
102f0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
10300 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 same.** trigger
10310 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e context..**.** ^
10320 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 Thus, when calle
10330 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c d from the top l
10340 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 evel, this funct
10350 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a ion returns the.
10360 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 ** number of cha
10370 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 nges in the most
10380 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 recent INSERT,
10390 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
103a0 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f E.** that also o
103b0 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 ccurred at the t
103c0 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 op level. ^(Wit
103d0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 hin the body of
103e0 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 a trigger,.** th
103f0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 e sqlite3_change
10400 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 s() interface ca
10410 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 n be called to f
10420 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ind the number o
10430 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 f.** changes in
10440 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c the most recentl
10450 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 y completed INSE
10460 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
10470 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 ELETE.** stateme
10480 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f nt within the bo
10490 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 dy of the same t
104a0 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 rigger..** Howev
104b0 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 er, the number r
104c0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 eturned does not
104d0 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 include changes
104e0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 .** caused by su
104f0 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 btriggers since
10500 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 those have their
10510 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a own context.)^.
10520 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 **.** See also t
10530 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 he [sqlite3_tota
10540 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 l_changes()] int
10550 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b erface, the.** [
10560 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 count_changes pr
10570 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b agma], and the [
10580 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 changes() SQL fu
10590 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
105a0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
105b0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
105c0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
105d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
105e0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 n.** while [sqli
105f0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 te3_changes()] i
10600 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 s running then t
10610 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
10620 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 d.** is unpredic
10630 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 table and not me
10640 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 aningful..*/.int
10650 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
10660 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
10670 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 ** CAPI3REF: Tot
10680 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 al Number Of Row
10690 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a s Modified.**.**
106a0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^This function
106b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
106c0 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 er of row change
106d0 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 s caused by [INS
106e0 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 ERT],.** [UPDATE
106f0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 ] or [DELETE] st
10700 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 atements since t
10710 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
10720 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 nection] was ope
10730 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f ned..** ^(The co
10740 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 unt returned by
10750 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
10760 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 anges() includes
10770 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 all changes.**
10780 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 from all [CREATE
10790 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
107a0 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 er] contexts and
107b0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 changes made by
107c0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 .** [foreign key
107d0 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 actions]. Howev
107e0 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 er,.** the count
107f0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
10800 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 e changes used t
10810 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 o implement [REP
10820 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 LACE] constraint
10830 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 s,.** do rollbac
10840 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 ks or ABORT proc
10850 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 essing, or [DROP
10860 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 TABLE] processi
10870 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e ng. The.** coun
10880 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 t does not inclu
10890 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 de rows of views
108a0 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 that fire an [I
108b0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
108c0 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 r],.** though if
108d0 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 the INSTEAD OF
108e0 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 trigger makes ch
108f0 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e anges of its own
10900 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 , those changes
10910 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e .** are counted.
10920 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 )^.** ^The sqlit
10930 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
10940 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e () function coun
10950 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 ts the changes a
10960 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 s soon as.** the
10970 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
10980 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f makes them is co
10990 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 mpleted (when th
109a0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 e statement hand
109b0 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 le.** is passed
109c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
109d0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
109e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a _finalize()])..*
109f0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
10a00 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
10a10 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c es()] interface,
10a20 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 the.** [count_c
10a30 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 hanges pragma],
10a40 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 and the [total_c
10a50 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
10a60 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
10a70 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
10a80 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 ad makes changes
10a90 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
10aa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
10ab0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 .** while [sqlit
10ac0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
10ad0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
10ae0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a hen the value.**
10af0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 returned is unp
10b00 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
10b10 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
10b20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f /.int sqlite3_to
10b30 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 tal_changes(sqli
10b40 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
10b50 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 PI3REF: Interrup
10b60 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 t A Long-Running
10b70 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 Query.**.** ^Th
10b80 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 is function caus
10b90 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 es any pending d
10ba0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
10bb0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a n to abort and.*
10bc0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 * return at its
10bd0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 earliest opportu
10be0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 nity. This routi
10bf0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a ne is typically.
10c00 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 ** called in res
10c10 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 ponse to a user
10c20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 action such as p
10c30 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 ressing "Cancel"
10c40 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 .** or Ctrl-C wh
10c50 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e ere the user wan
10c60 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 ts a long query
10c70 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c operation to hal
10c80 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 t.** immediately
10c90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 ..**.** ^It is s
10ca0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 afe to call this
10cb0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 routine from a
10cc0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 thread different
10cd0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 from the.** thr
10ce0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 ead that is curr
10cf0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 ently running th
10d00 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 e database opera
10d10 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a tion. But it.**
10d20 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
10d30 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e call this routin
10d40 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 e with a [databa
10d50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
10d60 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 hat.** is closed
10d70 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 or might close
10d80 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 before sqlite3_i
10d90 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 nterrupt() retur
10da0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ns..**.** ^If an
10db0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 SQL operation i
10dc0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 s very nearly fi
10dd0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 nished at the ti
10de0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 me when.** sqlit
10df0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 e3_interrupt() i
10e00 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 s called, then i
10e10 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 t might not have
10e20 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a an opportunity.
10e30 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 ** to be interru
10e40 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 pted and might c
10e50 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c ontinue to compl
10e60 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e etion..**.** ^An
10e70 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 SQL operation t
10e80 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 hat is interrupt
10e90 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b ed will return [
10ea0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
10eb0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e ]..** ^If the in
10ec0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 terrupted SQL op
10ed0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e eration is an IN
10ee0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
10ef0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 DELETE.** that
10f00 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 is inside an exp
10f10 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
10f20 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 n, then the enti
10f30 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a re transaction.*
10f40 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 * will be rolled
10f50 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 back automatica
10f60 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 lly..**.** ^(The
10f70 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
10f80 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e pt(D) call is in
10f90 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c effect until al
10fa0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e l currently runn
10fb0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
10fc0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 ments on [databa
10fd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
10fe0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 complete. Any
10ff0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e new SQL statemen
11000 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
11010 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
11020 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
11030 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 pt() call and be
11040 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e fore the .** run
11050 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 ning statements
11060 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
11070 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 interrupted as
11080 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e if they had been
11090 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f .** running prio
110a0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
110b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
110c0 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74 l. New SQL stat
110d0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
110e0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
110f0 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 the running sta
11100 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 tement count rea
11110 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a ches zero are.**
11120 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 not effected by
11130 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
11140 65 72 72 75 70 74 28 29 2e 29 5e 0a 2a 2a 20 5e errupt().)^.** ^
11150 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
11160 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 3_interrupt(D) t
11170 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 hat occurs when
11180 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e there are no run
11190 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
111a0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f ements is a no-o
111b0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 p and has no eff
111c0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 ect on SQL state
111d0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
111e0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
111f0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
11200 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 rrupt() call ret
11210 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 urns..**.** If t
11220 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
11230 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 ection closes wh
11240 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 ile [sqlite3_int
11250 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 errupt()].** is
11260 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 running then bad
11270 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b things will lik
11280 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 ely happen..*/.v
11290 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 oid sqlite3_inte
112a0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b rrupt(sqlite3*);
112b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
112c0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
112d0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
112e0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a Is Complete.**.*
112f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
11300 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 are useful duri
11310 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 ng command-line
11320 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 input to determi
11330 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 ne if the.** cur
11340 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 rently entered t
11350 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 ext seems to for
11360 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c m a complete SQL
11370 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a statement or.**
11380 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 if additional i
11390 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 nput is needed b
113a0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 efore sending th
113b0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 e text into.** S
113c0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e QLite for parsin
113d0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 g. ^These routi
113e0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 nes return 1 if
113f0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
11400 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 .** appears to b
11410 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c e a complete SQL
11420 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 statement. ^A
11430 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 statement is jud
11440 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d ged to be.** com
11450 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 plete if it ends
11460 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f with a semicolo
11470 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e n token and is n
11480 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 ot a prefix of a
11490 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 .** well-formed
114a0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 CREATE TRIGGER s
114b0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 tatement. ^Semi
114c0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 colons that are
114d0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a embedded within.
114e0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 ** string litera
114f0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 ls or quoted ide
11500 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 ntifier names or
11510 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f comments are no
11520 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 t.** independent
11530 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 tokens (they ar
11540 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f e part of the to
11550 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 ken in which the
11560 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 y are.** embedde
11570 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e d) and thus do n
11580 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 ot count as a st
11590 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 atement terminat
115a0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 or. ^Whitespace
115b0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 .** and comments
115c0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 that follow the
115d0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e final semicolon
115e0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a are ignored..**
115f0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
11600 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 nes return 0 if
11610 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
11620 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 incomplete. ^I
11630 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c f a.** memory al
11640 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 location fails,
11650 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 then SQLITE_NOME
11660 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a M is returned..*
11670 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
11680 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 ines do not pars
11690 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d e the SQL statem
116a0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c ents thus.** wil
116b0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e l not detect syn
116c0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 tactically incor
116d0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 rect SQL..**.**
116e0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 ^(If SQLite has
116f0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c not been initial
11700 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ized using [sqli
11710 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
11720 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 ] prior .** to i
11730 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f nvoking sqlite3_
11740 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 complete16() the
11750 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 n sqlite3_initia
11760 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
11770 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c d.** automatical
11780 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ly by sqlite3_co
11790 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 mplete16(). If
117a0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 that initializat
117b0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 ion fails,.** th
117c0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
117d0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
117e0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 _complete16() wi
117f0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a ll be non-zero.*
11800 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 * regardless of
11810 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
11820 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 he input SQL is
11830 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a complete.)^.**.*
11840 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b * The input to [
11850 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
11860 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
11870 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
11880 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a UTF-8 string..*
11890 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 *.** The input t
118a0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
118b0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 ete16()] must be
118c0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
118d0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
118e0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 ing in native by
118f0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 te order..*/.int
11900 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
11910 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 e(const char *sq
11920 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
11930 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 complete16(const
11940 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a void *sql);../*
11950 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
11960 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 gister A Callbac
11970 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 k To Handle SQLI
11980 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a TE_BUSY Errors.*
11990 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
119a0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 ne sets a callba
119b0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 ck function that
119c0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 might be invoke
119d0 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e d whenever.** an
119e0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 attempt is made
119f0 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 to open a datab
11a00 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 ase table that a
11a10 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a nother thread.**
11a20 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 or process has
11a30 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 locked..**.** ^I
11a40 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 f the busy callb
11a50 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ack is NULL, the
11a60 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 n [SQLITE_BUSY]
11a70 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
11a80 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 _BLOCKED].** is
11a90 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
11aa0 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e tely upon encoun
11ab0 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e tering the lock.
11ac0 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 ^If the busy c
11ad0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f allback.** is no
11ae0 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 t NULL, then the
11af0 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 callback might
11b00 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 be invoked with
11b10 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a two arguments..*
11b20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
11b30 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
11b40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 busy handler is
11b50 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f a copy of the vo
11b60 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 id* pointer whic
11b70 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 h.** is the thir
11b80 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
11b90 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
11ba0 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f er(). ^The seco
11bb0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
11bc0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c * the busy handl
11bd0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 er callback is t
11be0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d he number of tim
11bf0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 es that the busy
11c00 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 handler has.**
11c10 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 been invoked for
11c20 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 this locking ev
11c30 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a ent. ^If the.**
11c40 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 busy callback r
11c50 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e eturns 0, then n
11c60 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 o additional att
11c70 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 empts are made t
11c80 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 o.** access the
11c90 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 database and [SQ
11ca0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 LITE_BUSY] or [S
11cb0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
11cc0 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 KED] is returned
11cd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c ..** ^If the cal
11ce0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
11cf0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f n-zero, then ano
11d00 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 ther attempt.**
11d10 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 is made to open
11d20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 the database for
11d30 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 reading and the
11d40 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a cycle repeats..
11d50 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e **.** The presen
11d60 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e ce of a busy han
11d70 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 dler does not gu
11d80 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 arantee that it
11d90 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a will be invoked.
11da0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 ** when there is
11db0 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e lock contention
11dc0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 . ^If SQLite det
11dd0 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 ermines that inv
11de0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a oking the busy.*
11df0 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 * handler could
11e00 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 result in a dead
11e10 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f lock, it will go
11e20 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 ahead and retur
11e30 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a n [SQLITE_BUSY].
11e40 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f ** or [SQLITE_IO
11e50 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 ERR_BLOCKED] ins
11e60 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 tead of invoking
11e70 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
11e80 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 r..** Consider a
11e90 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 scenario where
11ea0 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 one process is h
11eb0 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f olding a read lo
11ec0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 ck that.** it is
11ed0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f trying to promo
11ee0 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 te to a reserved
11ef0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 lock and.** a s
11f00 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 econd process is
11f10 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 holding a reser
11f20 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 ved lock that it
11f30 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f is trying.** to
11f40 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 promote to an e
11f50 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 xclusive lock.
11f60 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 The first proces
11f70 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 s cannot proceed
11f80 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 .** because it i
11f90 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
11fa0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 second and the
11fb0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 second process c
11fc0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 annot.** proceed
11fd0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 because it is b
11fe0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 locked by the fi
11ff0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 rst. If both pr
12000 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b ocesses.** invok
12010 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c e the busy handl
12020 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c ers, neither wil
12030 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 l make any progr
12040 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c ess. Therefore,
12050 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 .** SQLite retur
12060 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ns [SQLITE_BUSY]
12070 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 for the first p
12080 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 rocess, hoping t
12090 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c hat this.** will
120a0 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 induce the firs
120b0 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c t process to rel
120c0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f ease its read lo
120d0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 ck and allow.**
120e0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
120f0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a ss to proceed..*
12100 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c *.** ^The defaul
12110 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 t busy callback
12120 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e is NULL..**.** ^
12130 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 The [SQLITE_BUSY
12140 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 ] error is conve
12150 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f rted to [SQLITE_
12160 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a IOERR_BLOCKED].*
12170 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
12180 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f in the middle o
12190 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 f a large transa
121a0 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 ction where all
121b0 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 the.** changes w
121c0 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f ill not fit into
121d0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 the in-memory c
121e0 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 ache. SQLite wi
121f0 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f ll.** already ho
12200 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f ld a RESERVED lo
12210 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 ck on the databa
12220 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 se file, but it
12230 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d needs.** to prom
12240 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f ote this lock to
12250 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 EXCLUSIVE so th
12260 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 at it can spill
12270 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 cache.** pages i
12280 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
12290 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 file without ha
122a0 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 rm to concurrent
122b0 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 .** readers. ^I
122c0 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 f it is unable t
122d0 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f o promote the lo
122e0 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d ck, then the in-
122f0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 memory.** cache
12300 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 will be left in
12310 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 an inconsistent
12320 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 state and so the
12330 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 error.** code i
12340 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 s promoted from
12350 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 the relatively b
12360 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 enign [SQLITE_BU
12370 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f SY] to.** the mo
12380 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 re severe [SQLIT
12390 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
123a0 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 . ^This error c
123b0 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a ode promotion.**
123c0 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d forces an autom
123d0 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 atic rollback of
123e0 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 the changes. S
123f0 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 ee the.** <a hre
12400 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 f="/cvstrac/wiki
12410 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c ?p=CorruptionFol
12420 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 lowingBusyError"
12430 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 >.** CorruptionF
12440 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f ollowingBusyErro
12450 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 r</a> wiki page
12460 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e for a discussion
12470 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 of why.** this
12480 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a is important..**
12490 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 .** ^(There can
124a0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 only be a single
124b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 busy handler de
124c0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a fined for each.*
124d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
124e0 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e ection]. Settin
124f0 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e g a new busy han
12500 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a dler clears any.
12510 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
12520 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e t handler.)^ ^N
12530 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 ote that calling
12540 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
12550 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c imeout()].** wil
12560 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c l also set or cl
12570 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e ear the busy han
12580 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 dler..**.** The
12590 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 busy callback sh
125a0 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e ould not take an
125b0 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 y actions which
125c0 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 modify the.** da
125d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
125e0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
125f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
12600 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f Any such actio
12610 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 ns.** result in
12620 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 undefined behavi
12630 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 or..** .** A bus
12640 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e y handler must n
12650 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ot close the dat
12660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
12670 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 .** or [prepared
12680 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
12690 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
126a0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e y handler..*/.in
126b0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 t sqlite3_busy_h
126c0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
126d0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e int(*)(void*,in
126e0 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a t), void*);../*.
126f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
12700 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a A Busy Timeout.
12710 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
12720 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 ine sets a [sqli
12730 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
12740 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d | busy handler]
12750 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 that sleeps.**
12760 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 for a specified
12770 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 amount of time w
12780 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c hen a table is l
12790 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e ocked. ^The han
127a0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 dler.** will sle
127b0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ep multiple time
127c0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 s until at least
127d0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
127e0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a ds of sleeping.*
127f0 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 * have accumulat
12800 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c ed. ^After at l
12810 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 east "ms" millis
12820 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
12830 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c ng,.** the handl
12840 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
12850 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ch causes [sqlit
12860 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
12870 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
12880 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
12890 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
128a0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 .**.** ^Calling
128b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 this routine wit
128c0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 h an argument le
128d0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c ss than or equal
128e0 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e to zero.** turn
128f0 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 s off all busy h
12900 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e andlers..**.** ^
12910 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 (There can only
12920 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 be a single busy
12930 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 handler for a p
12940 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 articular.** [da
12950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
12960 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e n] any any given
12970 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f moment. If ano
12980 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 ther busy handle
12990 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 r.** was defined
129a0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 (using [sqlite
129b0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
129c0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c ]) prior to call
129d0 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 ing.** this rout
129e0 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 ine, that other
129f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 busy handler is
12a00 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e cleared.)^.*/.in
12a10 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 t sqlite3_busy_t
12a20 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c imeout(sqlite3*,
12a30 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a int ms);../*.**
12a40 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 CAPI3REF: Conve
12a50 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 nience Routines
12a60 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 For Running Quer
12a70 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 ies.**.** Defini
12a80 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c tion: A <b>resul
12a90 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d t table</b> is m
12aa0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 emory data struc
12ab0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 ture created by
12ac0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
12ad0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 get_table()] int
12ae0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c erface. A resul
12af0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 t table records
12b00 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 the.** complete
12b10 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 query results fr
12b20 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 om one or more q
12b30 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ueries..**.** Th
12b40 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 e table conceptu
12b50 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 ally has a numbe
12b60 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f r of rows and co
12b70 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 lumns. But.** t
12b80 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 hese numbers are
12b90 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 not part of the
12ba0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 result table it
12bb0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 self. These.**
12bc0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 numbers are obta
12bd0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e ined separately.
12be0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e Let N be the n
12bf0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a umber of rows.**
12c00 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 and M be the nu
12c10 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e mber of columns.
12c20 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 .**.** A result
12c30 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 table is an arra
12c40 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
12c50 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
12c60 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a UTF-8 strings..
12c70 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b ** There are (N+
12c80 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 1)*M elements in
12c90 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 the array. The
12ca0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 first M pointer
12cb0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 s point.** to ze
12cc0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
12cd0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 rings that cont
12ce0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 ain the names of
12cf0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a the columns..**
12d00 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 The remaining e
12d10 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 ntries all point
12d20 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 to query result
12d30 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 s. NULL values
12d40 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c result.** in NUL
12d50 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c L pointers. All
12d60 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 other values ar
12d70 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 e in their UTF-8
12d80 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
12d90 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 .** string repre
12da0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 sentation as ret
12db0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
12dc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
12dd0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
12de0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e table might con
12df0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d sist of one or m
12e00 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ore memory alloc
12e10 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 ations..** It is
12e20 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 not safe to pas
12e30 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
12e40 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 directly to [sq
12e50 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a lite3_free()]..*
12e60 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
12e70 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c should be deall
12e80 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 ocated using [sq
12e90 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
12ea0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e ()]..**.** As an
12eb0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 example of the
12ec0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 result table for
12ed0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 mat, suppose a q
12ee0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 uery result.** i
12ef0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
12f00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
12f10 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
12f20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 Name | Ag
12f30 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d e.** ----
12f40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
12f50 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c ---.** Al
12f60 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a ice | 43.*
12f70 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 * Bob
12f80 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 | 28.**
12f90 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 Cindy
12fa0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f | 21.** </pre></
12fb0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
12fc0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 * There are two
12fd0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e column (M==2) an
12fe0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d d three rows (N=
12ff0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a =3). Thus the.*
13000 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 * result table h
13010 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 as 8 entries. S
13020 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c uppose the resul
13030 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 t table is store
13040 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 d.** in an array
13050 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e names azResult.
13060 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 Then azResult
13070 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 holds this conte
13080 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b nt:.**.** <block
13090 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
130a0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
130b0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 91;0] = "Name";.
130c0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
130d0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 lt[1] = "Age
130e0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
130f0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 esult[2] = "
13100 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 Alice";.**
13110 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 azResult[3
13120 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 ] = "43";.**
13130 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
13140 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 ;4] = "Bob";.**
13150 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
13160 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a #91;5] = "28";.*
13170 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
13180 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 t[6] = "Cind
13190 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a y";.** az
131a0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 Result[7] =
131b0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c "21";.** </pre><
131c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
131d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
131e0 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 get_table() func
131f0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f tion evaluates o
13200 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 ne or more.** se
13210 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 micolon-separate
13220 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 d SQL statements
13230 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 in the zero-ter
13240 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a minated UTF-8.**
13250 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 string of its 2
13260 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 nd parameter and
13270 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c returns a resul
13280 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a t table to the.*
13290 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 * pointer given
132a0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d in its 3rd param
132b0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 eter..**.** Afte
132c0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f r the applicatio
132d0 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 n has finished w
132e0 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 ith the result f
132f0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f rom sqlite3_get_
13300 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 73 table(),.** it s
13310 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65 20 72 hould pass the r
13320 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e esult table poin
13330 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 ter to sqlite3_f
13340 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f ree_table() in o
13350 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 rder to.** relea
13360 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 se the memory th
13370 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e at was malloced.
13380 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 Because of the
13390 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c way the.** [sql
133a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 ite3_malloc()] h
133b0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 appens within sq
133c0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
133d0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a ), the calling.*
133e0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
133f0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 not try to call
13400 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
13410 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 directly. Only
13420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
13430 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 e_table()] is ab
13440 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 le to release th
13450 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c e memory properl
13460 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a y and safely..**
13470 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 .** ^(The sqlite
13480 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 3_get_table() in
13490 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 terface is imple
134a0 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 mented as a wrap
134b0 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 per around.** [s
134c0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 qlite3_exec()].
134d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
134e0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 _table() routine
134f0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 does not have a
13500 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 ccess.** to any
13510 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 internal data st
13520 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 ructures of SQLi
13530 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c te. It uses onl
13540 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 y the public.**
13550 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 interface define
13560 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f d here. As a co
13570 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 nsequence, error
13580 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 s that occur in
13590 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c the.** wrapper l
135a0 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 ayer outside of
135b0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 the internal [sq
135c0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 lite3_exec()] ca
135d0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 ll are not.** re
135e0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 flected in subse
135f0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
13600 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
13610 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
13620 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a 3_errmsg()].)^.*
13630 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 /.int sqlite3_ge
13640 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 t_table(. sqlit
13650 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
13660 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 /* An open data
13670 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 base */. const
13680 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
13690 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 /* SQL to be eva
136a0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 luated */. char
136b0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 ***pazResult,
136c0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 /* Results of
136d0 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 the query */. i
136e0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 nt *pnRow,
136f0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
13700 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 f result rows wr
13710 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
13720 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 int *pnColumn,
13730 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
13740 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e of result column
13750 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a s written here *
13760 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 /. char **pzErr
13770 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 msg /* Err
13780 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
13790 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 ere */.);.void s
137a0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
137b0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 e(char **result)
137c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
137d0 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 F: Formatted Str
137e0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e ing Printing Fun
137f0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ctions.**.** The
13800 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
13810 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 work-alikes of t
13820 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 he "printf()" fa
13830 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e mily of function
13840 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 s.** from the st
13850 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
13860 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
13870 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 ite3_mprintf() a
13880 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 nd sqlite3_vmpri
13890 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 ntf() routines w
138a0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 rite their.** re
138b0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 sults into memor
138c0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
138d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
138e0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e )]..** The strin
138f0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 gs returned by t
13900 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 hese two routine
13910 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 s should be.** r
13920 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 eleased by [sqli
13930 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 te3_free()]. ^B
13940 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 oth routines ret
13950 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f urn a.** NULL po
13960 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 inter if [sqlite
13970 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 3_malloc()] is u
13980 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
13990 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f e enough.** memo
139a0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 ry to hold the r
139b0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e esulting string.
139c0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 .**.** ^(In sqli
139d0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 te3_snprintf() r
139e0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 outine is simila
139f0 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 r to "snprintf()
13a00 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 " from.** the st
13a10 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
13a20 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 . The result is
13a30 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
13a40 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 e.** buffer supp
13a50 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f lied as the seco
13a60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f nd parameter who
13a70 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e se size is given
13a80 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 by.** the first
13a90 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 parameter. Note
13aa0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 that the order
13ab0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 of the.** first
13ac0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 two parameters i
13ad0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 s reversed from
13ae0 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 snprintf().)^ T
13af0 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 his is an.** his
13b00 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 torical accident
13b10 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 that cannot be
13b20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 fixed without br
13b30 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 eaking.** backwa
13b40 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
13b50 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 y. ^(Note also
13b60 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 that sqlite3_snp
13b70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 rintf().** retur
13b80 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
13b90 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 its buffer inste
13ba0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 ad of the number
13bb0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 of.** character
13bc0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 s actually writt
13bd0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 en into the buff
13be0 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 er.)^ We admit
13bf0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 that.** the numb
13c00 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
13c10 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 written would b
13c20 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 e a more useful
13c30 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
13c40 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 but we cannot ch
13c50 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ange the impleme
13c60 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 ntation of sqlit
13c70 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
13c80 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 now without bre
13c90 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c aking compatibil
13ca0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c ity..**.** ^As l
13cb0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 ong as the buffe
13cc0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 r size is greate
13cd0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c r than zero, sql
13ce0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
13cf0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 ** guarantees th
13d00 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 at the buffer is
13d10 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 always zero-ter
13d20 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 minated. ^The f
13d30 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
13d40 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 r "n" is the tot
13d50 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 al size of the b
13d60 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 uffer, including
13d70 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 space for.** th
13d80 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
13d90 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 r. So the longe
13da0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 st string that c
13db0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 an be completely
13dc0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c .** written will
13dd0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 be n-1 characte
13de0 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 rs..**.** These
13df0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 routines all imp
13e00 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 lement some addi
13e10 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e tional formattin
13e20 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 g.** options tha
13e30 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 t are useful for
13e40 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 constructing SQ
13e50 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
13e60 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 All of the usua
13e70 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 l printf() forma
13e80 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 tting options ap
13e90 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f ply. In additio
13ea0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 n, there.** is a
13eb0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 re "%q", "%Q", a
13ec0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e nd "%z" options.
13ed0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 .**.** ^(The %q
13ee0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
13ef0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 e %s in that it
13f00 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 substitutes a nu
13f10 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ll-terminated.**
13f20 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
13f30 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
13f40 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
13f50 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
13f60 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
13f70 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
13f80 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
13f90 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 ring literal.)^
13fa0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 By doubling eac
13fb0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 h '\''.** charac
13fc0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 ter it escapes t
13fd0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e hat character an
13fe0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 d allows it to b
13ff0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a e inserted into.
14000 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a ** the string..*
14010 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
14020 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 , assume the str
14030 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 ing variable zTe
14040 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 xt contains text
14050 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
14060 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
14070 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
14080 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 Text = "It's a h
14090 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c appy day!";.** <
140a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
140b0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e e>.**.** One can
140c0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 use this text i
140d0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
140e0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a nt as follows:.*
140f0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
14100 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
14110 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
14120 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
14130 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
14140 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 S('%q')", zText)
14150 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
14160 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
14170 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
14180 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
14190 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
141a0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 uote>.**.** Beca
141b0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 use the %q forma
141c0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 t string is used
141d0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 , the '\'' chara
141e0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a cter in zText.**
141f0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 is escaped and
14200 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 the SQL generate
14210 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a d is as follows:
14220 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
14230 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
14240 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
14250 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 VALUES('It''s a
14260 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 happy day!').**
14270 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
14280 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te>.**.** This i
14290 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 s correct. Had
142a0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 we used %s inste
142b0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 ad of %q, the ge
142c0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 nerated SQL.** w
142d0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 ould have looked
142e0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
142f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
14300 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
14310 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
14320 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 S('It's a happy
14330 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 day!');.** </pre
14340 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
14350 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 *.** This second
14360 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 example is an S
14370 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e QL syntax error.
14380 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 As a general r
14390 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a ule you should.*
143a0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 * always use %q
143b0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 instead of %s wh
143c0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 en inserting tex
143d0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 t into a string
143e0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e literal..**.** ^
143f0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 (The %Q option w
14400 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 orks like %q exc
14410 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 ept it also adds
14420 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 single quotes a
14430 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 round.** the out
14440 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 side of the tota
14450 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 l string. Addit
14460 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 ionally, if the
14470 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
14480 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 .** argument lis
14490 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
144a0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 ter, %Q substitu
144b0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 tes the text "NU
144c0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 LL" (without.**
144d0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 single quotes).)
144e0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 ^ So, for examp
144f0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 le, one could sa
14500 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 y:.**.** <blockq
14510 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
14520 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
14530 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
14540 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
14550 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 ALUES(%Q)", zTex
14560 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f t);.** sqlite3_
14570 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 exec(db, zSQL, 0
14580 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c , 0, 0);.** sql
14590 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b ite3_free(zSQL);
145a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
145b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
145c0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c e code above wil
145d0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 l render a corre
145e0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ct SQL statement
145f0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 in the zSQL.**
14600 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 variable even if
14610 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 the zText varia
14620 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ble is a NULL po
14630 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 inter..**.** ^(T
14640 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 he "%z" formatti
14650 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 ng option works
14660 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 like "%s" but wi
14670 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 th the.** additi
14680 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 on that after th
14690 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 e string has bee
146a0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 n read and copie
146b0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 d into.** the re
146c0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 sult, [sqlite3_f
146d0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 ree()] is called
146e0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 on the input st
146f0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 ring.)^.*/.char
14700 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 *sqlite3_mprintf
14710 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e (const char*,...
14720 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
14730 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 _vmprintf(const
14740 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
14750 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 .char *sqlite3_s
14760 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 nprintf(int,char
14770 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e *,const char*, .
14780 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
14790 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
147a0 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 ocation Subsyste
147b0 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 m.**.** The SQLi
147c0 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 te core uses the
147d0 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 se three routine
147e0 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 s for all of its
147f0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c own.** internal
14800 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14810 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 on needs. "Core"
14820 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 in the previous
14830 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 sentence.** doe
14840 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 s not include op
14850 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 erating-system s
14860 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c pecific VFS impl
14870 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 ementation. The
14880 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 .** Windows VFS
14890 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c uses native mall
148a0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
148b0 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 for some operati
148c0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ons..**.** ^The
148d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
148e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
148f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
14900 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f block.** of memo
14910 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 ry at least N by
14920 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 tes in length, w
14930 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 here N is the pa
14940 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 rameter..** ^If
14950 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14960 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 is unable to ob
14970 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 tain sufficient
14980 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 free.** memory,
14990 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c it returns a NUL
149a0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 L pointer. ^If
149b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 the parameter N
149c0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 to.** sqlite3_ma
149d0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
149e0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 r negative then
149f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14a00 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 returns.** a NU
14a10 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
14a20 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 * ^Calling sqlit
14a30 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 e3_free() with a
14a40 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 pointer previou
14a50 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 sly returned.**
14a60 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f by sqlite3_mallo
14a70 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
14a80 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 ealloc() release
14a90 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f s that memory so
14aa0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 .** that it migh
14ab0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 t be reused. ^T
14ac0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 he sqlite3_free(
14ad0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 ) routine is.**
14ae0 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 a no-op if is ca
14af0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
14b00 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 pointer. Passi
14b10 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ng a NULL pointe
14b20 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f r.** to sqlite3_
14b30 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 free() is harmle
14b40 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 ss. After being
14b50 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a freed, memory.*
14b60 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 * should neither
14b70 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 be read nor wri
14b80 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 tten. Even read
14b90 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ing previously f
14ba0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d reed.** memory m
14bb0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 ight result in a
14bc0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
14bd0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 ult or other sev
14be0 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 ere error..** Me
14bf0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c mory corruption,
14c00 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
14c10 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 fault, or other
14c20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 severe error.**
14c30 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
14c40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
14c50 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
14c60 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
14c70 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 that.** was not
14c80 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
14c90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
14ca0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
14cb0 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 oc()..**.** ^(Th
14cc0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f e sqlite3_reallo
14cd0 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 c() interface at
14ce0 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 tempts to resize
14cf0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f a.** prior memo
14d00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
14d10 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 be at least N b
14d20 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 ytes, where N is
14d30 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 the.** second p
14d40 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d arameter. The m
14d50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14d60 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 to be resized i
14d70 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 s the first.** p
14d80 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 arameter.)^ ^ If
14d90 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
14da0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
14db0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 realloc().** is
14dc0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
14dd0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 hen its behavior
14de0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f is identical to
14df0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
14e00 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 te3_malloc(N) wh
14e10 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
14e20 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
14e30 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
14e40 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 ()..** ^If the s
14e50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
14e60 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
14e70 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a oc() is zero or.
14e80 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e ** negative then
14e90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
14ea0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d exactly the sam
14eb0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 e as calling.**
14ec0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 sqlite3_free(P)
14ed0 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 where P is the f
14ee0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
14ef0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
14f00 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 c()..** ^sqlite3
14f10 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 _realloc() retur
14f20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
14f30 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
14f40 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 ion.** of at lea
14f50 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 st N bytes in si
14f60 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 ze or NULL if su
14f70 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 fficient memory
14f80 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a is unavailable..
14f90 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 ** ^If M is the
14fa0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f size of the prio
14fb0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 r allocation, th
14fc0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 en min(N,M) byte
14fd0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f s.** of the prio
14fe0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 r allocation are
14ff0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 copied into the
15000 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 beginning of bu
15010 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a ffer returned.**
15020 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c by sqlite3_real
15030 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 loc() and the pr
15040 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 ior allocation i
15050 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 s freed..** ^If
15060 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
15070 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 ) returns NULL,
15080 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 then the prior a
15090 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 llocation.** is
150a0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a not freed..**.**
150b0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 ^The memory ret
150c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
150d0 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 _malloc() and sq
150e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a lite3_realloc().
150f0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
15100 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
15110 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
15120 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 ary..**.** In SQ
15130 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
15140 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 .0 and 3.5.1, it
15150 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f was possible to
15160 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 define.** the S
15170 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 QLITE_OMIT_MEMOR
15180 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 Y_ALLOCATION whi
15190 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 ch would cause t
151a0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 he built-in.** i
151b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
151c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
151d0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 to be omitted.
151e0 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a That capability.
151f0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ** is no longer
15200 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 provided. Only
15210 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
15220 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 allocators can b
15230 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 e used..**.** Th
15240 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 e Windows OS int
15250 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c erface layer cal
15260 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d ls.** the system
15270 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
15280 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 ee() directly wh
15290 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a en converting.**
152a0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 filenames betwe
152b0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 en the UTF-8 enc
152c0 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 oding used by SQ
152d0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 Lite.** and what
152e0 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e ever filename en
152f0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 coding is used b
15300 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 y the particular
15310 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 Windows.** inst
15320 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 allation. Memor
15330 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
15340 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 ors are detected
15350 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 , but.** they ar
15360 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 e reported back
15370 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f as [SQLITE_CANTO
15380 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 PEN] or.** [SQLI
15390 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 TE_IOERR] rather
153a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f than [SQLITE_NO
153b0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 MEM]..**.** The
153c0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 pointer argument
153d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 s to [sqlite3_fr
153e0 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ee()] and [sqlit
153f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
15400 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
15410 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 NULL or else poi
15420 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 nters obtained f
15430 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 rom a prior.** i
15440 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
15450 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
15460 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
15470 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 loc()] that have
15480 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e .** not yet been
15490 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a released..**.**
154a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
154b0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f must not read o
154c0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 r write any part
154d0 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f of.** a block o
154e0 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 f memory after i
154f0 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 t has been relea
15500 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 sed using.** [sq
15510 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 lite3_free()] or
15520 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
15530 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 c()]..*/.void *s
15540 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e qlite3_malloc(in
15550 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 t);.void *sqlite
15560 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 3_realloc(void*,
15570 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
15580 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b te3_free(void*);
15590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
155a0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
155b0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a or Statistics.**
155c0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 .** SQLite provi
155d0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e des these two in
155e0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 terfaces for rep
155f0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 orting on the st
15600 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b atus.** of the [
15610 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
15620 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ], [sqlite3_free
15630 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
15640 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
15650 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 routines, which
15660 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 form the built-i
15670 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
15680 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a ion subsystem..*
15690 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
156a0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
156b0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
156c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
156d0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f bytes.** of memo
156e0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 ry currently out
156f0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 standing (malloc
15700 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 ed but not freed
15710 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 )..** ^The [sqli
15720 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
15730 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 ater()] routine
15740 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 returns the maxi
15750 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 mum.** value of
15760 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
15770 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 used()] since th
15780 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 e high-water mar
15790 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 k.** was last re
157a0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 set. ^The value
157b0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
157c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
157d0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ed()] and.** [sq
157e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
157f0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 hwater()] includ
15800 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a e any overhead.*
15810 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 * added by SQLit
15820 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 e in its impleme
15830 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ntation of [sqli
15840 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a te3_malloc()],.*
15850 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 * but not overhe
15860 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 ad added by the
15870 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 any underlying s
15880 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a ystem library.**
15890 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b routines that [
158a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
158b0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a ] may call..**.*
158c0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 * ^The memory hi
158d0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 gh-water mark is
158e0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 reset to the cu
158f0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a rrent value of.*
15900 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
15910 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 y_used()] if and
15920 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 only if the par
15930 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
15940 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
15950 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 hwater()] is tru
15960 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 e. ^The value r
15970 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 eturned.** by [s
15980 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
15990 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 ghwater(1)] is t
159a0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
159b0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 rk.** prior to t
159c0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c he reset..*/.sql
159d0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
159e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
159f0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e oid);.sqlite3_in
15a00 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
15a10 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 ry_highwater(int
15a20 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a resetFlag);../*
15a30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 .** CAPI3REF: Ps
15a40 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 eudo-Random Numb
15a50 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a er Generator.**.
15a60 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 ** SQLite contai
15a70 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 ns a high-qualit
15a80 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 y pseudo-random
15a90 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 number generator
15aa0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a (PRNG) used to.
15ab0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d ** select random
15ac0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 [ROWID | ROWIDs
15ad0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 ] when inserting
15ae0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 new records int
15af0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a o a table that.*
15b00 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 * already uses t
15b10 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 he largest possi
15b20 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 ble [ROWID]. Th
15b30 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 e PRNG is also u
15b40 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 sed for.** the b
15b50 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 uild-in random()
15b60 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 and randomblob(
15b70 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e ) SQL functions.
15b80 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 This interface
15b90 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 allows.** appli
15ba0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 cations to acces
15bb0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 s the same PRNG
15bc0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 for other purpos
15bd0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c es..**.** ^A cal
15be0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e l to this routin
15bf0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 e stores N bytes
15c00 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 of randomness i
15c10 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a nto buffer P..**
15c20 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 .** ^The first t
15c30 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ime this routine
15c40 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 is invoked (eit
15c50 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f her internally o
15c60 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c r by.** the appl
15c70 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e ication) the PRN
15c80 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e G is seeded usin
15c90 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 g randomness obt
15ca0 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 ained.** from th
15cb0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 e xRandomness me
15cc0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 thod of the defa
15cd0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
15ce0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e ] object..** ^On
15cf0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 all subsequent
15d00 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 invocations, the
15d10 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 pseudo-randomne
15d20 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a ss is generated.
15d30 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e ** internally an
15d40 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 d without recour
15d50 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 se to the [sqlit
15d60 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e e3_vfs] xRandomn
15d70 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a ess.** method..*
15d80 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 /.void sqlite3_r
15d90 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c andomness(int N,
15da0 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a void *P);../*.*
15db0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 * CAPI3REF: Comp
15dc0 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 ile-Time Authori
15dd0 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 zation Callbacks
15de0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
15df0 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 tine registers a
15e00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
15e10 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 back with a part
15e20 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
15e30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c ase connection],
15e40 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 supplied in the
15e50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
15e60 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 .** ^The authori
15e70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
15e80 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 invoked as SQL s
15e90 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 tatements are be
15ea0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 ing compiled.**
15eb0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 by [sqlite3_prep
15ec0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
15ed0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f riants [sqlite3_
15ee0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a prepare_v2()],.*
15ef0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
15f00 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c re16()] and [sql
15f10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
15f20 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 2()]. ^At vario
15f30 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 us.** points dur
15f40 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 ing the compilat
15f50 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 ion process, as
15f60 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 logic is being c
15f70 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 reated.** to per
15f80 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 form various act
15f90 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 ions, the author
15fa0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
15fb0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 invoked to.** s
15fc0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 ee if those acti
15fd0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e ons are allowed.
15fe0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ^The authorize
15ff0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c r callback shoul
16000 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c d.** return [SQL
16010 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 ITE_OK] to allow
16020 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 the action, [SQ
16030 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 LITE_IGNORE] to
16040 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 disallow the.**
16050 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 specific action
16060 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 but allow the SQ
16070 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 L statement to c
16080 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a ontinue to be.**
16090 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 compiled, or [S
160a0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 QLITE_DENY] to c
160b0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 ause the entire
160c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
160d0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 be.** rejected
160e0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 with an error.
160f0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a ^If the authoriz
16100 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 er callback retu
16110 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 rns.** any value
16120 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
16130 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 ITE_IGNORE], [SQ
16140 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 LITE_OK], or [SQ
16150 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 LITE_DENY].** th
16160 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f en the [sqlite3_
16170 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
16180 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
16190 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a that triggered.
161a0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
161b0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
161c0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
161d0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
161e0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
161f0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ns [SQLITE_OK],
16200 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f that means the o
16210 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 peration.** requ
16220 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 ested is ok. ^W
16230 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
16240 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
16250 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b _DENY], the.** [
16260 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
16270 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
16280 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
16290 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 iggered the.** a
162a0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
162b0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
162c0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 r message explai
162d0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 ning that.** acc
162e0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a ess is denied. .
162f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
16300 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
16310 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
16320 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 lback is a copy
16330 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 of the third.**
16340 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
16350 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
16360 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 horizer() interf
16370 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 ace. ^The second
16380 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
16390 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
163a0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c an integer [SQL
163b0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
163c0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
163d0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 cifies.** the pa
163e0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 rticular action
163f0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
16400 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 . ^The third thr
16410 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d ough sixth param
16420 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 eters.** to the
16430 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 callback are zer
16440 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
16450 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 ings that contai
16460 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 n additional.**
16470 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 details about th
16480 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 e action to be a
16490 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a uthorized..**.**
164a0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 ^If the action
164b0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
164c0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 READ].** and the
164d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
164e0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 s [SQLITE_IGNORE
164f0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 ] then the.** [p
16500 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
16510 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 t] statement is
16520 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 constructed to s
16530 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e ubstitute.** a N
16540 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 ULL value in pla
16550 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 ce of the table
16560 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c column that woul
16570 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 d have.** been r
16580 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f ead if [SQLITE_O
16590 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 K] had been retu
165a0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 rned. The [SQLI
165b0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 TE_IGNORE].** re
165c0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 turn can be used
165d0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 to deny an untr
165e0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 usted user acces
165f0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a s to individual.
16600 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 ** columns of a
16610 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 table..** ^If th
16620 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 e action code is
16630 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d [SQLITE_DELETE]
16640 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
16650 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 k returns.** [SQ
16660 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
16670 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f n the [DELETE] o
16680 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 peration proceed
16690 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 s but the.** [tr
166a0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 uncate optimizat
166b0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 ion] is disabled
166c0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 and all rows ar
166d0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 e deleted indivi
166e0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e dually..**.** An
166f0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 authorizer is u
16700 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 sed when [sqlite
16710 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
16720 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 aring].** SQL st
16730 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e atements from an
16740 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
16750 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 e, to ensure tha
16760 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
16770 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 ents.** do not t
16780 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 ry to access dat
16790 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 a they are not a
167a0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f llowed to see, o
167b0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e r that they do n
167c0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 ot.** try to exe
167d0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 cute malicious s
167e0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 tatements that d
167f0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 amage the databa
16800 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d se. For.** exam
16810 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ple, an applicat
16820 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 ion may allow a
16830 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 user to enter ar
16840 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 bitrary.** SQL q
16850 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 ueries for evalu
16860 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 ation by a datab
16870 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 ase. But the ap
16880 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a plication does.*
16890 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 * not want the u
168a0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 ser to be able t
168b0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 o make arbitrary
168c0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a changes to the.
168d0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e ** database. An
168e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c authorizer coul
168f0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e d then be put in
16900 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 place while the
16910 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 .** user-entered
16920 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 SQL is being [s
16930 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
16940 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a prepared] that.
16950 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 ** disallows eve
16960 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b rything except [
16970 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
16980 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ts..**.** Applic
16990 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 ations that need
169a0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 to process SQL
169b0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 from untrusted s
169c0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 ources.** might
169d0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f also consider lo
169e0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 wering resource
169f0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 limits using [sq
16a00 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
16a10 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 * and limiting d
16a20 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 atabase size usi
16a30 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 ng the [max_page
16a40 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
16a50 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 .** in addition
16a60 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 to using an auth
16a70 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 orizer..**.** ^(
16a80 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 Only a single au
16a90 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 thorizer can be
16aa0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 in place on a da
16ab0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16ac0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 n.** at a time.
16ad0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 Each call to sq
16ae0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
16af0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 izer overrides t
16b00 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 he.** previous c
16b10 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 all.)^ ^Disable
16b20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
16b30 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 by installing a
16b40 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a NULL callback..*
16b50 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
16b60 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
16b70 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 default..**.** T
16b80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
16b90 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 llback must not
16ba0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
16bb0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
16bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
16bd0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
16be0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 oked the authori
16bf0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a zer callback..**
16c00 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
16c10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
16c20 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
16c30 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
16c40 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
16c50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
16c60 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
16c70 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
16c80 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
16c90 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c **.** ^When [sql
16ca0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
16cb0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 )] is used to pr
16cc0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
16cd0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d t, the.** statem
16ce0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d ent might be re-
16cf0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 prepared during
16d00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
16d10 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 due to a .** sc
16d20 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 hema change. He
16d30 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 nce, the applica
16d40 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 tion should ensu
16d50 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 re that the.** c
16d60 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 orrect authorize
16d70 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 r callback remai
16d80 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 ns in place duri
16d90 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ng the [sqlite3_
16da0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e step()]..**.** ^
16db0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 Note that the au
16dc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
16dd0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c k is invoked onl
16de0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c y during.** [sql
16df0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
16e00 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
16e10 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 Authorization
16e20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 is not.** perfor
16e30 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 med during state
16e40 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 ment evaluation
16e50 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 in [sqlite3_step
16e60 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 ()], unless.** a
16e70 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 s stated in the
16e80 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 previous paragra
16e90 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 ph, sqlite3_step
16ea0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 () invokes.** sq
16eb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
16ec0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 () to reprepare
16ed0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 a statement afte
16ee0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 r a schema chang
16ef0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
16f00 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
16f10 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 (. sqlite3*,.
16f20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 int (*xAuth)(voi
16f30 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
16f40 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
16f50 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
16f60 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 char*),. void
16f70 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f *pUserData.);../
16f80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
16f90 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e uthorizer Return
16fa0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
16fb0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
16fc0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
16fd0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 rizer callback f
16fe0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a unction] must.**
16ff0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b return either [
17000 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e SQLITE_OK] or on
17010 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 e of these two c
17020 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 onstants in orde
17030 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 r.** to signal S
17040 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 QLite whether or
17050 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 not the action
17060 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 is permitted. S
17070 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ee the.** [sqlit
17080 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
17090 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 r | authorizer d
170a0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
170b0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
170c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
170d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
170e0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f ENY 1 /* Abo
170f0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 rt the SQL state
17100 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 ment with an err
17110 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
17120 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 LITE_IGNORE 2
17130 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 /* Don't allow a
17140 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 ccess, but don't
17150 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 generate an err
17160 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 or */../*.** CAP
17170 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 I3REF: Authorize
17180 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a r Action Codes.*
17190 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
171a0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
171b0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 ()] interface re
171c0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
171d0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 ck function.** t
171e0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 hat is invoked t
171f0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 o authorize cert
17200 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ain SQL statemen
17210 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a t actions. The.
17220 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
17230 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ter to the callb
17240 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ack is an intege
17250 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 r code that spec
17260 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 ifies.** what ac
17270 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 tion is being au
17280 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 thorized. These
17290 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 are the integer
172a0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 action codes th
172b0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 at.** the author
172c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 izer callback ma
172d0 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a y be passed..**.
172e0 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 ** These action
172f0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e code values sign
17300 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 ify what kind of
17310 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f operation is to
17320 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 be.** authorize
17330 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 d. The 3rd and
17340 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 4th parameters t
17350 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 o the authorizat
17360 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 ion.** callback
17370 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 function will be
17380 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e parameters or N
17390 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ULL depending on
173a0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a which of these.
173b0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 ** codes is used
173c0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
173d0 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 arameter. ^The
173e0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
173f0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
17400 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 er callback is t
17410 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
17420 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c atabase ("main",
17430 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e "temp",.** etc.
17440 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e ) if applicable.
17450 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d ^The 6th param
17460 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
17470 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a orizer callback.
17480 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
17490 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 f the inner-most
174a0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 trigger or view
174b0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 that is respons
174c0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 ible for.** the
174d0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f access attempt o
174e0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 r NULL if this a
174f0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 ccess attempt is
17500 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a directly from.*
17510 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 * top-level SQL
17520 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a code..*/./******
17530 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
17540 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
17550 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a ***** 3rd ******
17560 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a ****** 4th *****
17570 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 ******/.#define
17580 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e SQLITE_CREATE_IN
17590 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 DEX 1
175a0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
175b0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
175c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
175d0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 QLITE_CREATE_TAB
175e0 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 LE 2
175f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
17600 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
17610 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17620 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
17630 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f _INDEX 3 /
17640 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
17650 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
17660 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
17670 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
17680 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a TABLE 4 /*
17690 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
176a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
176b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
176c0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
176d0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 RIGGER 5 /*
176e0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
176f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
17700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17710 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 E_CREATE_TEMP_VI
17720 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 EW 6 /* V
17730 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
17740 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
17750 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17760 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 _CREATE_TRIGGER
17770 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 7 /* Tr
17780 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
17790 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
177a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
177b0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 CREATE_VIEW
177c0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 8 /* Vie
177d0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
177e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
177f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
17800 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 ELETE
17810 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 9 /* Tabl
17820 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
17830 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
17840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
17850 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 OP_INDEX
17860 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 10 /* Index
17870 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
17880 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
17890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
178a0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 P_TABLE
178b0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 11 /* Table
178c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
178d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
178e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
178f0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
17900 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 12 /* Index N
17910 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
17920 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
17930 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
17940 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 TEMP_TABLE
17950 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 13 /* Table Na
17960 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
17970 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
17980 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
17990 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 EMP_TRIGGER 1
179a0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 4 /* Trigger N
179b0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
179c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
179d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
179e0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 MP_VIEW 15
179f0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
17a00 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
17a10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
17a20 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 SQLITE_DROP_TRI
17a30 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 GGER 16
17a40 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
17a50 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
17a60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
17a70 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 SQLITE_DROP_VIEW
17a80 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 17
17a90 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
17aa0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
17ab0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
17ac0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 QLITE_INSERT
17ad0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 18
17ae0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
17af0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
17b00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17b10 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 LITE_PRAGMA
17b20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 19 /
17b30 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 * Pragma Name
17b40 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 1st arg or NUL
17b50 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c L */.#define SQL
17b60 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 ITE_READ
17b70 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 /*
17b80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
17b90 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 Column Name
17ba0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17bb0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 TE_SELECT
17bc0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 21 /*
17bd0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
17be0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
17bf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17c00 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 E_TRANSACTION
17c10 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 22 /* O
17c20 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e peration N
17c30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
17c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17c50 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 _UPDATE
17c60 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 23 /* Ta
17c70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
17c80 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
17c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17ca0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 ATTACH
17cb0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 24 /* Fil
17cc0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c ename NUL
17cd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
17ce0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
17cf0 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 ETACH
17d00 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 25 /* Data
17d10 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c base Name NULL
17d20 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
17d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c define SQLITE_AL
17d40 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 TER_TABLE
17d50 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 26 /* Datab
17d60 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 ase Name Table
17d70 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
17d80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 efine SQLITE_REI
17d90 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 NDEX
17da0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 27 /* Index
17db0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
17dc0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
17dd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c fine SQLITE_ANAL
17de0 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 YZE
17df0 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 28 /* Table N
17e00 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
17e10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
17e20 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
17e30 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 E_VTABLE
17e40 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 29 /* Table Na
17e50 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
17e60 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
17e70 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 ne SQLITE_DROP_V
17e80 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 TABLE 3
17e90 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
17ea0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
17eb0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
17ec0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f e SQLITE_FUNCTIO
17ed0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 N 31
17ee0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
17ef0 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e Function N
17f00 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 ame */.#define
17f10 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e SQLITE_SAVEPOIN
17f20 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 T 32
17f30 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 /* Operation
17f40 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e Savepoint N
17f50 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ame */.#define
17f60 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 SQLITE_COPY
17f70 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 0
17f80 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 /* No longer us
17f90 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ed */../*.** CAP
17fa0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 I3REF: Tracing A
17fb0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e nd Profiling Fun
17fc0 63 74 69 6f 6e 73 0a 2a 2a 20 45 58 50 45 52 49 ctions.** EXPERI
17fd0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
17fe0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 se routines regi
17ff0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 ster callback fu
18000 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e nctions that can
18010 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 be used for.**
18020 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 tracing and prof
18030 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 iling the execut
18040 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 ion of SQL state
18050 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
18060 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
18070 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
18080 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 y sqlite3_trace(
18090 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a ) is invoked at.
180a0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 ** various times
180b0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 when an SQL sta
180c0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 tement is being
180d0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f run by [sqlite3_
180e0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 step()]..** ^The
180f0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
18100 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
18110 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d oked with a UTF-
18120 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 8 rendering of t
18130 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d he.** SQL statem
18140 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 ent text as the
18150 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 statement first
18160 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 begins executing
18170 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 ..** ^(Additiona
18180 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 l sqlite3_trace(
18190 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 ) callbacks migh
181a0 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 t occur.** as ea
181b0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 ch triggered sub
181c0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 program is enter
181d0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 ed. The callbac
181e0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a ks for triggers.
181f0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 ** contain a UTF
18200 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 -8 SQL comment t
18210 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 hat identifies t
18220 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a he trigger.)^.**
18230 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 .** ^The callbac
18240 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
18250 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
18260 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e _profile() is in
18270 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 voked.** as each
18280 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
18290 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 inishes. ^The p
182a0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
182b0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
182c0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
182d0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 nt text and an e
182e0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d stimate of wall-
182f0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 clock time.** of
18300 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 how long that s
18310 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f tatement took to
18320 20 72 75 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f run..*/.SQLITE_
18330 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 EXPERIMENTAL voi
18340 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 d *sqlite3_trace
18350 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 (sqlite3*, void(
18360 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 *xTrace)(void*,c
18370 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 onst char*), voi
18380 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 d*);.SQLITE_EXPE
18390 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 RIMENTAL void *s
183a0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 qlite3_profile(s
183b0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 qlite3*,. void
183c0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 (*xProfile)(void
183d0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 *,const char*,sq
183e0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 lite3_uint64), v
183f0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
18400 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 PI3REF: Query Pr
18410 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 ogress Callbacks
18420 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
18430 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 tine configures
18440 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
18450 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f ion - the.** pro
18460 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d gress callback -
18470 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 that is invoked
18480 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
18490 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e ring long.** run
184a0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 ning calls to [s
184b0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
184c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
184d0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
184e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 _get_table()].
184f0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 An example use f
18500 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 or this.** inter
18510 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 face is to keep
18520 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 a GUI updated du
18530 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 ring a large que
18540 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ry..**.** ^If th
18550 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
18560 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
18570 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 zero, the operat
18580 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 ion is.** interr
18590 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 upted. This fea
185a0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 ture can be used
185b0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a to implement a.
185c0 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 ** "Cancel" butt
185d0 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 on on a GUI prog
185e0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e ress dialog box.
185f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 .**.** The progr
18600 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 ess handler must
18610 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
18620 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
18630 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
18640 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
18650 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 t invoked the pr
18660 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a ogress handler..
18670 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
18680 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
18690 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
186a0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
186b0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
186c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
186d0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
186e0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
186f0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
18700 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c ..**.*/.void sql
18710 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
18720 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 ndler(sqlite3*,
18730 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 int, int(*)(void
18740 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a *), void*);../*.
18750 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 ** CAPI3REF: Ope
18760 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 ning A New Datab
18770 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase Connection.*
18780 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
18790 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c ines open an SQL
187a0 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c ite database fil
187b0 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 e whose name is
187c0 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 given by the.**
187d0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
187e0 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 t. ^The filename
187f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 argument is int
18800 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d erpreted as UTF-
18810 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 8 for.** sqlite3
18820 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
18830 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e te3_open_v2() an
18840 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 d as UTF-16 in t
18850 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a he native byte.*
18860 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 * order for sqli
18870 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 te3_open16(). ^(
18880 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e A [database conn
18890 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 ection] handle i
188a0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 s usually.** ret
188b0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 urned in *ppDb,
188c0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 even if an error
188d0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e occurs. The on
188e0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 ly exception is
188f0 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 that.** if SQLit
18900 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 e is unable to a
18910 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 llocate memory t
18920 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 o hold the [sqli
18930 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 te3] object,.**
18940 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 a NULL will be w
18950 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 ritten into *ppD
18960 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 b instead of a p
18970 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ointer to the [s
18980 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 qlite3].** objec
18990 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 t.)^ ^(If the da
189a0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
189b0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 (and/or created
189c0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 ) successfully,
189d0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f then.** [SQLITE_
189e0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e OK] is returned.
189f0 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b Otherwise an [
18a00 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
18a10 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a eturned.)^ ^The.
18a20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ** [sqlite3_errm
18a30 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 sg()] or [sqlite
18a40 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 3_errmsg16()] ro
18a50 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 utines can be us
18a60 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 ed to obtain.**
18a70 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 an English langu
18a80 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 age description
18a90 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c of the error fol
18aa0 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 lowing a failure
18ab0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 of any.** of th
18ac0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 e sqlite3_open()
18ad0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
18ae0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e ^The default en
18af0 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 coding for the d
18b00 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 atabase will be
18b10 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 UTF-8 if.** sqli
18b20 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
18b30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
18b40 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a is called and.**
18b50 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
18b60 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
18b70 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e if sqlite3_open
18b80 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 16() is used..**
18b90 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e .** Whether or n
18ba0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 ot an error occu
18bb0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 rs when it is op
18bc0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a ened, resources.
18bd0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
18be0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
18bf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
18c00 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 dle should be re
18c10 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 leased by.** pas
18c20 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 sing it to [sqli
18c30 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 te3_close()] whe
18c40 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 n it is no longe
18c50 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a r required..**.*
18c60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 * The sqlite3_op
18c70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 en_v2() interfac
18c80 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c e works like sql
18c90 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 ite3_open().** e
18ca0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 xcept that it ac
18cb0 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 cepts two additi
18cc0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 onal parameters
18cd0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 for additional c
18ce0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 ontrol.** over t
18cf0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 he new database
18d00 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 connection. ^(T
18d10 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
18d20 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 er to.** sqlite3
18d30 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 _open_v2() can t
18d40 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 ake one of.** th
18d50 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 e following thre
18d60 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e e values, option
18d70 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 ally combined wi
18d80 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 th the .** [SQLI
18d90 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
18da0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 , [SQLITE_OPEN_F
18db0 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 ULLMUTEX], [SQLI
18dc0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
18dd0 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 CHE],.** and/or
18de0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 [SQLITE_OPEN_PRI
18df0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 VATECACHE] flags
18e00 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a :)^.**.** <dl>.*
18e10 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f * ^(<dt>[SQLITE_
18e20 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f OPEN_READONLY]</
18e30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
18e40 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
18e50 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d d in read-only m
18e60 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 ode. If the dat
18e70 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a abase does not.*
18e80 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c * already exist,
18e90 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
18ea0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a urned.</dd>)^.**
18eb0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
18ec0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
18ed0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
18ee0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
18ef0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 ened for reading
18f00 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 and writing if
18f10 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 possible, or rea
18f20 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 ding.** only if
18f30 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 the file is writ
18f40 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 e protected by t
18f50 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
18f60 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a tem. In either.
18f70 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 ** case the data
18f80 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 base must alread
18f90 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 y exist, otherwi
18fa0 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 se an error is r
18fb0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
18fc0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c **.** ^(<dt>[SQL
18fd0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
18fe0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 TE] | [SQLITE_OP
18ff0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a EN_CREATE]</dt>.
19000 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 ** <dd>The datab
19010 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f ase is opened fo
19020 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 r reading and wr
19030 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 iting, and is cr
19040 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 eates it if.** i
19050 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 t does not alrea
19060 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 dy exist. This i
19070 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 s the behavior t
19080 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 hat is always us
19090 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 ed for.** sqlite
190a0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
190b0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f ite3_open16().</
190c0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a dd>)^.** </dl>.*
190d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 *.** If the 3rd
190e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
190f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
19100 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 s not one of the
19110 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 .** combinations
19120 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 shown above or
19130 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 one of the combi
19140 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 nations shown ab
19150 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 ove combined.**
19160 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
19170 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 _OPEN_NOMUTEX],
19180 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
19190 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c LMUTEX],.** [SQL
191a0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
191b0 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 ACHE] and/or [SQ
191c0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
191d0 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a CACHE] flags,.**
191e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
191f0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
19200 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b .**.** ^If the [
19210 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
19220 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 TEX] flag is set
19230 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
19240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
19250 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d * opens in the m
19260 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 ulti-thread [thr
19270 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 eading mode] as
19280 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 long as the sing
19290 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 le-thread.** mod
192a0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 e has not been s
192b0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 et at compile-ti
192c0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 me or start-time
192d0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 . ^If the.** [S
192e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
192f0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
19300 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 t then the datab
19310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
19320 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 pens.** in the s
19330 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
19340 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 ding mode] unles
19350 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 s single-thread
19360 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c was.** previousl
19370 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f y selected at co
19380 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 mpile-time or st
19390 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 art-time..** ^Th
193a0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 e [SQLITE_OPEN_S
193b0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 HAREDCACHE] flag
193c0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
193d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
193e0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c to be.** eligibl
193f0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 e to use [shared
19400 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 cache mode], re
19410 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
19420 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
19430 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e d.** cache is en
19440 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c abled using [sql
19450 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
19460 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 ed_cache()]. ^T
19470 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 he.** [SQLITE_OP
19480 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d EN_PRIVATECACHE]
19490 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 flag causes the
194a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
194b0 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 tion to not.** p
194c0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 articipate in [s
194d0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
194e0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 ] even if it is
194f0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e enabled..**.** ^
19500 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
19510 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 is ":memory:", t
19520 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 hen a private, t
19530 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f emporary in-memo
19540 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 ry database.** i
19550 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 s created for th
19560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e e connection. ^
19570 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 This in-memory d
19580 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e atabase will van
19590 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 ish when.** the
195a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
195b0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 ion is closed.
195c0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
195d0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a of SQLite might.
195e0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 ** make use of a
195f0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 dditional specia
19600 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 l filenames that
19610 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 begin with the
19620 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ":" character..*
19630 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * It is recommen
19640 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 ded that when a
19650 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d database filenam
19660 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 e actually does
19670 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 begin with.** a
19680 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f ":" character yo
19690 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 u should prefix
196a0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 the filename wit
196b0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 h a pathname suc
196c0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 h as.** "./" to
196d0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e avoid ambiguity.
196e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
196f0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d ilename is an em
19700 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e pty string, then
19710 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 a private, temp
19720 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b orary.** on-disk
19730 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
19740 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 e created. ^Thi
19750 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 s private databa
19760 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 se will be.** au
19770 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 tomatically dele
19780 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 ted as soon as t
19790 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
197a0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
197b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
197c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
197d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
197e0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f () is the name o
197f0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
19800 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 3_vfs] object th
19810 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f at defines the o
19820 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
19830 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a interface that.*
19840 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 * the new databa
19850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 se connection sh
19860 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 ould use. ^If t
19870 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
19880 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c ter is.** a NULL
19890 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
198a0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
198b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 e3_vfs] object i
198c0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 s used..**.** <b
198d0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 >Note to Windows
198e0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
198f0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 encoding used f
19900 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 or the filename
19910 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 argument.** of s
19920 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
19930 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
19940 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 2() must be UTF-
19950 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 8, not whatever.
19960 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 ** codepage is c
19970 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
19980 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e . Filenames con
19990 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 taining internat
199a0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 ional.** charact
199b0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ers must be conv
199c0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 erted to UTF-8 p
199d0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 rior to passing
199e0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c them into.** sql
199f0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
19a00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
19a10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
19a20 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 _open(. const c
19a30 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 har *filename,
19a40 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
19a50 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f ename (UTF-8) */
19a60 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
19a70 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b /* OU
19a80 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
19a90 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 dle */.);.int sq
19aa0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 lite3_open16(.
19ab0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 const void *file
19ac0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
19ad0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
19ae0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 F-16) */. sqlit
19af0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
19b00 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
19b10 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
19b20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 ;.int sqlite3_op
19b30 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 en_v2(. const c
19b40 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 har *filename,
19b50 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
19b60 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f ename (UTF-8) */
19b70 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
19b80 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b, /* OU
19b90 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
19ba0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 dle */. int fla
19bb0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 gs,
19bc0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 /* Flags */. c
19bd0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 onst char *zVfs
19be0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
19bf0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 f VFS module to
19c00 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a use */.);../*.**
19c10 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 CAPI3REF: Error
19c20 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 Codes And Messa
19c30 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ges.**.** ^The s
19c40 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
19c50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
19c60 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b ns the numeric [
19c70 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a result code] or.
19c80 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
19c90 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ult code] for th
19ca0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 e most recent fa
19cb0 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 iled sqlite3_* A
19cc0 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 PI call.** assoc
19cd0 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 iated with a [da
19ce0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
19cf0 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 n]. If a prior A
19d00 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a PI call failed.*
19d10 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 * but the most r
19d20 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 ecent API call s
19d30 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 ucceeded, the re
19d40 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a turn value from.
19d50 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f ** sqlite3_errco
19d60 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 de() is undefine
19d70 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 d. ^The sqlite3
19d80 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 _extended_errcod
19d90 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 e().** interface
19da0 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 is the same exc
19db0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 ept that it alwa
19dc0 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a ys returns the .
19dd0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
19de0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 ult code] even w
19df0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 hen extended res
19e00 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a ult codes are.**
19e10 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a disabled..**.**
19e20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 ^The sqlite3_er
19e30 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 rmsg() and sqlit
19e40 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 e3_errmsg16() re
19e50 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e turn English-lan
19e60 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 guage.** text th
19e70 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 at describes the
19e80 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 error, as eithe
19e90 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 r UTF-8 or UTF-1
19ea0 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 6 respectively..
19eb0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 ** ^(Memory to h
19ec0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 old the error me
19ed0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
19ee0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c managed internal
19ef0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ly..** The appli
19f00 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 cation does not
19f10 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 need to worry ab
19f20 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 out freeing the
19f30 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 result..** Howev
19f40 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 er, the error st
19f50 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 ring might be ov
19f60 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 erwritten or dea
19f70 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 llocated by.** s
19f80 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
19f90 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 to other SQLite
19fa0 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 interface functi
19fb0 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 ons.)^.**.** Whe
19fc0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 n the serialized
19fd0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
19fe0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 ] is in use, it
19ff0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 might be the.**
1a000 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f case that a seco
1a010 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 nd error occurs
1a020 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 on a separate th
1a030 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a read in between.
1a040 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 ** the time of t
1a050 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 he first error a
1a060 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 nd the call to t
1a070 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e hese interfaces.
1a080 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 .** When that ha
1a090 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e ppens, the secon
1a0a0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 d error will be
1a0b0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 reported since t
1a0c0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 hese.** interfac
1a0d0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 es always report
1a0e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
1a0f0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f result. To avo
1a100 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 id.** this, each
1a110 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 thread can obta
1a120 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 in exclusive use
1a130 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
1a140 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a e connection] D.
1a150 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b ** by invoking [
1a160 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
1a170 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ter]([sqlite3_db
1a180 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f _mutex](D)) befo
1a190 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 re beginning.**
1a1a0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 to use D and inv
1a1b0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
1a1c0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c utex_leave]([sql
1a1d0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
1a1e0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 )) after.** all
1a1f0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 calls to the int
1a200 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 erfaces listed h
1a210 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 ere are complete
1a220 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 d..**.** If an i
1a230 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 nterface fails w
1a240 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 ith SQLITE_MISUS
1a250 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 E, that means th
1a260 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 e interface.** w
1a270 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 as invoked incor
1a280 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 rectly by the ap
1a290 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 plication. In t
1a2a0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a hat case, the.**
1a2b0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
1a2c0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d message may or m
1a2d0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a ay not be set..*
1a2e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 /.int sqlite3_er
1a2f0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 rcode(sqlite3 *d
1a300 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f b);.int sqlite3_
1a310 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 extended_errcode
1a320 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 (sqlite3 *db);.c
1a330 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1a340 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 e3_errmsg(sqlite
1a350 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 3*);.const void
1a360 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 *sqlite3_errmsg1
1a370 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 6(sqlite3*);../*
1a380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
1a390 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 L Statement Obje
1a3a0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
1a3b0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d {prepared statem
1a3c0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 ent} {prepared s
1a3d0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a tatements}.**.**
1a3e0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
1a3f0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 this object repr
1a400 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 esents a single
1a410 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a SQL statement..*
1a420 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
1a430 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e variously known
1a440 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 as a "prepared
1a450 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a statement" or a.
1a460 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c ** "compiled SQL
1a470 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 statement" or s
1a480 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 imply as a "stat
1a490 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 ement"..**.** Th
1a4a0 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 e life of a stat
1a4b0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 ement object goe
1a4c0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 s something like
1a4d0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c this:.**.** <ol
1a4e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 >.** <li> Create
1a4f0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
1a500 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
1a510 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 re_v2()] or a re
1a520 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 lated.** fu
1a530 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 nction..** <li>
1a540 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b Bind values to [
1a550 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d host parameters]
1a560 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
1a570 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 e3_bind_*().**
1a580 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a interfaces..
1a590 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 ** <li> Run the
1a5a0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b SQL by calling [
1a5b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1a5c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
1a5d0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 s..** <li> Reset
1a5e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 the statement u
1a5f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 sing [sqlite3_re
1a600 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 set()] then go b
1a610 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 ack.** to s
1a620 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 tep 2. Do this
1a630 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d zero or more tim
1a640 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 es..** <li> Dest
1a650 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 roy the object u
1a660 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
1a670 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f nalize()]..** </
1a680 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 ol>.**.** Refer
1a690 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e to documentation
1a6a0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d on individual m
1a6b0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 ethods above for
1a6c0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
1a6d0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 nformation..*/.t
1a6e0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
1a6f0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 lite3_stmt sqlit
1a700 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 e3_stmt;../*.**
1a710 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 CAPI3REF: Run-ti
1a720 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 me Limits.**.**
1a730 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 ^(This interface
1a740 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 allows the size
1a750 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 of various cons
1a760 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d tructs to be lim
1a770 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e ited.** on a con
1a780 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 nection by conne
1a790 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 ction basis. Th
1a7a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
1a7b0 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 r is the.** [dat
1a7c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1a7d0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 ] whose limit is
1a7e0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 to be set or qu
1a7f0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 eried. The.** s
1a800 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1a810 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c is one of the [l
1a820 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d imit categories]
1a830 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a that define a.*
1a840 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 * class of const
1a850 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 ructs to be size
1a860 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 limited. The t
1a870 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
1a880 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d s the.** new lim
1a890 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 it for that cons
1a8a0 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 truct. The func
1a8b0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
1a8c0 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a old limit.)^.**
1a8d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 .** ^If the new
1a8e0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 limit is a negat
1a8f0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 ive number, the
1a900 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 limit is unchang
1a910 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65 ed..** ^(For the
1a920 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 limit category
1a930 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f of SQLITE_LIMIT_
1a940 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a XYZ there is a .
1a950 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 ** [limits | har
1a960 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a d upper bound].*
1a970 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 * set by a compi
1a980 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f le-time C prepro
1a990 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d cessor macro nam
1a9a0 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c ed .** [limits |
1a9b0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d SQLITE_MAX_XYZ]
1a9c0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 ..** (The "_LIMI
1a9d0 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 T_" in the name
1a9e0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f is changed to "_
1a9f0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 MAX_".))^.** ^At
1aa00 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 tempts to increa
1aa10 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 se a limit above
1aa20 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 its hard upper
1aa30 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c bound are.** sil
1aa40 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 ently truncated
1aa50 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 to the hard uppe
1aa60 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 r limit..**.** R
1aa70 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 un-time limits a
1aa80 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
1aa90 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 use in applicati
1aaa0 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a ons that manage.
1aab0 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 ** both their ow
1aac0 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 n internal datab
1aad0 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 ase and also dat
1aae0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 abases that are
1aaf0 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 controlled.** by
1ab00 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 untrusted exter
1ab10 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e nal sources. An
1ab20 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 example applica
1ab30 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a tion might be a.
1ab40 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 ** web browser t
1ab50 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 hat has its own
1ab60 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 databases for st
1ab70 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e oring history an
1ab80 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 d.** separate da
1ab90 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c tabases controll
1aba0 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 ed by JavaScript
1abb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f applications do
1abc0 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 wnloaded.** off
1abd0 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 the Internet. T
1abe0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 he internal data
1abf0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 bases can be giv
1ac00 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c en the.** large,
1ac10 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e default limits.
1ac20 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 Databases mana
1ac30 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 ged by external
1ac40 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 sources can.** b
1ac50 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 e given much sma
1ac60 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 ller limits desi
1ac70 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 gned to prevent
1ac80 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 a denial of serv
1ac90 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 ice.** attack.
1aca0 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 Developers might
1acb0 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 also want to us
1acc0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 e the [sqlite3_s
1acd0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d et_authorizer()]
1ace0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f .** interface to
1acf0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c further control
1ad00 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 untrusted SQL.
1ad10 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 The size of the
1ad20 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 database.** cre
1ad30 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 ated by an untru
1ad40 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 sted script can
1ad50 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 be contained usi
1ad60 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 ng the.** [max_p
1ad70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 age_count] [PRAG
1ad80 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 MA]..**.** New r
1ad90 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 un-time limit ca
1ada0 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 tegories may be
1adb0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
1adc0 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 releases..*/.int
1add0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 sqlite3_limit(s
1ade0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c qlite3*, int id,
1adf0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f int newVal);../
1ae00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1ae10 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 un-Time Limit Ca
1ae20 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 tegories.** KEYW
1ae30 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 ORDS: {limit cat
1ae40 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 egory} {*limit c
1ae50 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a ategories}.**.**
1ae60 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
1ae70 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 define various
1ae80 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 performance limi
1ae90 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 ts.** that can b
1aea0 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e e lowered at run
1aeb0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c -time using [sql
1aec0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a ite3_limit()]..*
1aed0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f * The synopsis o
1aee0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f f the meanings o
1aef0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 f the various li
1af00 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 mits is shown be
1af10 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e low..** Addition
1af20 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 al information i
1af30 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b s available at [
1af40 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 limits | Limits
1af50 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a in SQLite]..**.*
1af60 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e * <dl>.** ^(<dt>
1af70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
1af80 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
1af90 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 The maximum size
1afa0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f of any string o
1afb0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 r BLOB or table
1afc0 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a row.<dd>)^.**.**
1afd0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
1afe0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f MIT_SQL_LENGTH</
1aff0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
1b000 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
1b010 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
1b020 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 t.</dd>)^.**.**
1b030 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
1b040 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a IT_COLUMN</dt>.*
1b050 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1b060 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
1b070 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 mns in a table d
1b080 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 efinition or in
1b090 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 the.** result se
1b0a0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 t of a [SELECT]
1b0b0 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e or the maximum n
1b0c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
1b0d0 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 in an index.**
1b0e0 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 or in an ORDER B
1b0f0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c Y or GROUP BY cl
1b100 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ause.</dd>)^.**.
1b110 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
1b120 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 LIMIT_EXPR_DEPTH
1b130 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1b140 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f maximum depth o
1b150 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 f the parse tree
1b160 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 on any expressi
1b170 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a on.</dd>)^.**.**
1b180 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
1b190 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
1b1a0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ECT</dt>.** <dd>
1b1b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1b1c0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 er of terms in a
1b1d0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 compound SELECT
1b1e0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e statement.</dd>
1b1f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 )^.**.** ^(<dt>S
1b200 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
1b210 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e _OP</dt>.** <dd>
1b220 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1b230 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f er of instructio
1b240 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 ns in a virtual
1b250 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a machine program.
1b260 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 ** used to imple
1b270 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 ment an SQL stat
1b280 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ement.</dd>)^.**
1b290 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
1b2a0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
1b2b0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
1b2c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1b2d0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
1b2e0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
1b2f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
1b300 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 t>SQLITE_LIMIT_A
1b310 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 TTACHED</dt>.**
1b320 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
1b330 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 number of [ATTAC
1b340 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 H | attached dat
1b350 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a abases].</dd>.**
1b360 0a 2a 2a 20 5e 3c 64 74 3e 53 51 4c 49 54 45 5f .** ^<dt>SQLITE_
1b370 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
1b380 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a RN_LENGTH</dt>.*
1b390 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1b3a0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 m length of the
1b3b0 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 pattern argument
1b3c0 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f to the [LIKE] o
1b3d0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 r.** [GLOB] oper
1b3e0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ators.</dd>)^.**
1b3f0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
1b400 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
1b410 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c NUMBER</dt>.** <
1b420 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
1b430 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c umber of variabl
1b440 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 es in an SQL sta
1b450 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a tement that can.
1b460 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 ** be bound.</dd
1b470 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
1b480 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 SQLITE_LIMIT_TRI
1b490 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a GGER_DEPTH</dt>.
1b4a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1b4b0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 um depth of recu
1b4c0 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 rsion for trigge
1b4d0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f rs.</dd>)^.** </
1b4e0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
1b4f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
1b500 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
1b510 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
1b520 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
1b530 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
1b540 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
1b550 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
1b560 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 LUMN
1b570 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
1b580 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 e SQLITE_LIMIT_E
1b590 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 XPR_DEPTH
1b5a0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 3.#defi
1b5b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
1b5c0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 COMPOUND_SELECT
1b5d0 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
1b5e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
1b5f0 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 _VDBE_OP
1b600 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 5.#de
1b610 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
1b620 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 T_FUNCTION_ARG
1b630 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
1b640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
1b650 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 IT_ATTACHED
1b660 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 7.#
1b670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
1b680 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
1b690 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a _LENGTH 8.
1b6a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1b6b0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
1b6c0 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 MBER 9
1b6d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b6e0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 LIMIT_TRIGGER_DE
1b6f0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 PTH 1
1b700 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
1b710 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 F: Compiling An
1b720 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL Statement.**
1b730 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
1b740 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c statement compil
1b750 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 er}.**.** To exe
1b760 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 cute an SQL quer
1b770 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 y, it must first
1b780 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 be compiled int
1b790 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a o a byte-code.**
1b7a0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f program using o
1b7b0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ne of these rout
1b7c0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ines..**.** The
1b7d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 first argument,
1b7e0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 "db", is a [data
1b7f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1b800 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
1b810 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 .** prior succes
1b820 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
1b830 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
1b840 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1b850 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
1b860 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 3_open16()]. Th
1b870 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1b880 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 ction must not h
1b890 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e ave been closed.
1b8a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
1b8b0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 d argument, "zSq
1b8c0 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 l", is the state
1b8d0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
1b8e0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 led, encoded.**
1b8f0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
1b900 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 or UTF-16. The
1b910 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
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 5f 76 32 28 29 0a 2a 2a 20 69 6e epare_v2().** in
1b940 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 terfaces use UTF
1b950 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f -8, and sqlite3_
1b960 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 prepare16() and
1b970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1b980 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 6_v2().** use UT
1b990 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 F-16..**.** ^If
1b9a0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 the nByte argume
1b9b0 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 nt is less than
1b9c0 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 zero, then zSql
1b9d0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 is read up to th
1b9e0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 e.** first zero
1b9f0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 terminator. ^If
1ba00 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 nByte is non-neg
1ba10 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 ative, then it i
1ba20 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a s the maximum.**
1ba30 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 number of byte
1ba40 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c s read from zSql
1ba50 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 . ^When nByte i
1ba60 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
1ba70 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 the.** zSql stri
1ba80 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 ng ends at eithe
1ba90 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 r the first '\00
1baa0 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 0' or '\u0000' c
1bab0 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 haracter or.** t
1bac0 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 he nByte-th byte
1bad0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 , whichever come
1bae0 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 s first. If the
1baf0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 caller knows.**
1bb00 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 that the supplie
1bb10 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d d string is nul-
1bb20 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e terminated, then
1bb30 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c there is a smal
1bb40 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 l.** performance
1bb50 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 advantage to be
1bb60 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 gained by passi
1bb70 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 ng an nByte para
1bb80 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 meter that.** is
1bb90 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 equal to the nu
1bba0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
1bbb0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
1bbc0 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f g <i>including</
1bbd0 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 i>.** the nul-te
1bbe0 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a rminator bytes..
1bbf0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c **.** ^If pzTail
1bc00 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 is not NULL the
1bc10 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 n *pzTail is mad
1bc20 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 e to point to th
1bc30 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 e first byte.**
1bc40 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 past the end of
1bc50 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 the first SQL st
1bc60 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e atement in zSql.
1bc70 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
1bc80 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 only.** compile
1bc90 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 the first state
1bca0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f ment in zSql, so
1bcb0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 *pzTail is left
1bcc0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 pointing to.**
1bcd0 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 what remains unc
1bce0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ompiled..**.** ^
1bcf0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 *ppStmt is left
1bd00 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f pointing to a co
1bd10 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 mpiled [prepared
1bd20 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
1bd30 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 can be.** execu
1bd40 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
1bd50 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 e3_step()]. ^If
1bd60 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 there is an err
1bd70 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 or, *ppStmt is s
1bd80 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 et.** to NULL.
1bd90 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 ^If the input te
1bda0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 xt contains no S
1bdb0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 QL (if the input
1bdc0 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 is an empty.**
1bdd0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d string or a comm
1bde0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d ent) then *ppStm
1bdf0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c t is set to NULL
1be00 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 ..** The calling
1be10 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 procedure is re
1be20 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 sponsible for de
1be30 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 leting the compi
1be40 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 led.** SQL state
1be50 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ment using [sqli
1be60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
1be70 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e after it has fin
1be80 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a ished with it..*
1be90 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 * ppStmt may not
1bea0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
1beb0 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 ^On success, the
1bec0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1bed0 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 () family of rou
1bee0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
1bef0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 LITE_OK];.** oth
1bf00 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
1bf10 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
1bf20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
1bf30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1bf40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
1bf50 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e repare16_v2() in
1bf60 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 terfaces are.**
1bf70 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
1bf80 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 all new programs
1bf90 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 . The two older
1bfa0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 interfaces are r
1bfb0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 etained.** for b
1bfc0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
1bfd0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 bility, but thei
1bfe0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 r use is discour
1bff0 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 aged..** ^In the
1c000 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 "v2" interfaces
1c010 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 , the prepared s
1c020 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 tatement.** that
1c030 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 is returned (th
1c040 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
1c050 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e object) contain
1c060 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
1c070 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 ** original SQL
1c080 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 text. This cause
1c090 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 s the [sqlite3_s
1c0a0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tep()] interface
1c0b0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 to.** behave di
1c0c0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 fferently in thr
1c0d0 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ee ways:.**.** <
1c0e0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e ol>.** <li>.** ^
1c0f0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
1c100 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 schema changes,
1c110 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 instead of retur
1c120 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 ning [SQLITE_SCH
1c130 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c EMA] as it.** al
1c140 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c ways used to do,
1c150 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1c160 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 ] will automatic
1c170 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 ally recompile t
1c180 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d he SQL.** statem
1c190 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 ent and try to r
1c1a0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49 un it again. ^I
1c1b0 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 f the schema has
1c1c0 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 changed in.** a
1c1d0 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 way that makes
1c1e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f the statement no
1c1f0 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b longer valid, [
1c200 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1c210 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 will still.** re
1c220 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 turn [SQLITE_SCH
1c230 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b EMA]. But unlik
1c240 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 e the legacy beh
1c250 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 avior, [SQLITE_S
1c260 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 CHEMA] is.** now
1c270 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 a fatal error.
1c280 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 Calling [sqlite
1c290 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1c2a0 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d again will not m
1c2b0 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 ake the.** error
1c2c0 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a go away. Note:
1c2d0 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 use [sqlite3_er
1c2e0 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 rmsg()] to find
1c2f0 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 the text.** of t
1c300 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 he parsing error
1c310 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e that results in
1c320 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 an [SQLITE_SCHE
1c330 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c MA] return..** <
1c340 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a /li>.**.** <li>.
1c350 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f ** ^When an erro
1c360 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 r occurs, [sqlit
1c370 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
1c380 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 return one of th
1c390 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 e detailed.** [e
1c3a0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b rror codes] or [
1c3b0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
1c3c0 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 odes]. ^The leg
1c3d0 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 acy behavior was
1c3e0 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 that.** [sqlite
1c3f0 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 3_step()] would
1c400 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 only return a ge
1c410 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 neric [SQLITE_ER
1c420 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 ROR] result code
1c430 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c .** and you woul
1c440 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 d have to make a
1c450 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 second call to
1c460 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
1c470 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f ] in order.** to
1c480 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c find the underl
1c490 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 ying cause of th
1c4a0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 e problem. With
1c4b0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 the "v2" prepare
1c4c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 .** interfaces,
1c4d0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 the underlying r
1c4e0 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 eason for the er
1c4f0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 ror is returned
1c500 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 immediately..**
1c510 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e </li>.**.** <li>
1c520 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 .** ^If the valu
1c530 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65 e of a [paramete
1c540 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 r | host paramet
1c550 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45 er] in the WHERE
1c560 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a clause might.**
1c570 20 63 68 61 6e 67 65 20 74 68 65 20 71 75 65 72 change the quer
1c580 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 y plan for a sta
1c590 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 tement, then the
1c5a0 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62 statement may b
1c5b0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c e.** automatical
1c5c0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61 ly recompiled (a
1c5d0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 s if there had b
1c5e0 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61 een a schema cha
1c5f0 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73 nge) on the firs
1c600 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 t .** [sqlite3_s
1c610 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c tep()] call foll
1c620 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 owing any change
1c630 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c to the .** [sql
1c640 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c ite3_bind_text |
1c650 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 bindings] of th
1c660 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a e [parameter]. .
1c670 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c ** </li>.** </ol
1c680 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 >.*/.int sqlite3
1c690 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 _prepare(. sqli
1c6a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1c6b0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
1c6c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1c6d0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
1c6e0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
1c6f0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f ment, UTF-8 enco
1c700 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
1c710 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
1c720 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
1c730 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
1c740 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
1c750 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
1c760 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
1c770 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
1c780 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
1c790 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
1c7a0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
1c7b0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
1c7c0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 l */.);.int sqli
1c7d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a te3_prepare_v2(.
1c7e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1c7f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
1c800 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
1c810 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
1c820 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
1c830 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
1c840 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
1c850 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
1c860 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
1c870 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
1c880 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
1c890 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
1c8a0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
1c8b0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
1c8c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1c8d0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
1c8e0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
1c8f0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
1c900 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e of zSql */.);.in
1c910 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
1c920 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a e16(. sqlite3 *
1c930 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
1c940 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
1c950 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
1c960 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f d *zSql, /
1c970 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
1c980 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
1c990 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
1c9a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
1c9b0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
1c9c0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
1c9d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
1c9e0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
1c9f0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
1ca00 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1ca10 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 t void **pzTail
1ca20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
1ca30 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
1ca40 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
1ca50 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
1ca60 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 prepare16_v2(.
1ca70 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
1ca80 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
1ca90 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
1caa0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c const void *zSql
1cab0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
1cac0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 tatement, UTF-16
1cad0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
1cae0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
1caf0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
1cb00 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
1cb10 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
1cb20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
1cb30 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
1cb40 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
1cb50 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
1cb60 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
1cb70 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
1cb80 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
1cb90 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a f zSql */.);../*
1cba0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
1cbb0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 trieving Stateme
1cbc0 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 nt SQL.**.** ^Th
1cbd0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
1cbe0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 be used to retr
1cbf0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 ieve a saved cop
1cc00 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 y of the origina
1cc10 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 l.** SQL text us
1cc20 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b ed to create a [
1cc30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1cc40 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 nt] if that stat
1cc50 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d ement was.** com
1cc60 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 piled using eith
1cc70 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
1cc80 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
1cc90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
1cca0 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 v2()]..*/.const
1ccb0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 char *sqlite3_sq
1ccc0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a l(sqlite3_stmt *
1ccd0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
1cce0 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 API3REF: Dynamic
1ccf0 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 ally Typed Value
1cd00 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f Object.** KEYWO
1cd10 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 RDS: {protected
1cd20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b sqlite3_value} {
1cd30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
1cd40 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a te3_value}.**.**
1cd50 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 SQLite uses the
1cd60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1cd70 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 bject to represe
1cd80 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a nt all values.**
1cd90 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f that can be sto
1cda0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 red in a databas
1cdb0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 e table. SQLite
1cdc0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 uses dynamic typ
1cdd0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 ing.** for the v
1cde0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e alues it stores.
1cdf0 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 ^Values stored
1ce00 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 in sqlite3_valu
1ce10 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e e objects.** can
1ce20 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c be integers, fl
1ce30 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
1ce40 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c ues, strings, BL
1ce50 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a OBs, or NULL..**
1ce60 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 .** An sqlite3_v
1ce70 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 alue object may
1ce80 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 be either "prote
1ce90 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 cted" or "unprot
1cea0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 ected"..** Some
1ceb0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 interfaces requi
1cec0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 re a protected s
1ced0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f qlite3_value. O
1cee0 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a ther interfaces.
1cef0 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 ** will accept e
1cf00 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 ither a protecte
1cf10 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 d or an unprotec
1cf20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
1cf30 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 e..** Every inte
1cf40 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 rface that accep
1cf50 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ts sqlite3_value
1cf60 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 arguments speci
1cf70 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 fies.** whether
1cf80 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 or not it requir
1cf90 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 es a protected s
1cfa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a qlite3_value..**
1cfb0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 .** The terms "p
1cfc0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 rotected" and "u
1cfd0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 nprotected" refe
1cfe0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 r to whether or
1cff0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 not.** a mutex i
1d000 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 s held. A inter
1d010 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c nal mutex is hel
1d020 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 d for a protecte
1d030 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
1d040 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f ue object but no
1d050 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
1d060 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
1d070 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
1d080 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 ue object. If S
1d090 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
1d0a0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 d to be single-t
1d0b0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 hreaded.** (with
1d0c0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1d0d0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 AFE=0] and with
1d0e0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 [sqlite3_threads
1d0f0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 afe()] returning
1d100 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 0).** or if SQL
1d110 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e ite is run in on
1d120 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 e of reduced mut
1d130 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 ex modes .** [SQ
1d140 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
1d150 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 LETHREAD] or [SQ
1d160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
1d170 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e ITHREAD].** then
1d180 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 there is no dis
1d190 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
1d1a0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
1d1b0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
1d1c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1d1d0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e cts and they can
1d1e0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 be used interch
1d1f0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 angeably. Howev
1d200 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d er,.** for maxim
1d210 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c um code portabil
1d220 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d ity it is recomm
1d230 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 ended that appli
1d240 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c cations.** still
1d250 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e make the distin
1d260 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 ction between be
1d270 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
1d280 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
1d290 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
1d2a0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 objects even wh
1d2b0 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 en not strictly
1d2c0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
1d2d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
1d2e0 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 ue objects that
1d2f0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 are passed as pa
1d300 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 rameters into th
1d310 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
1d320 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 ion of [applicat
1d330 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
1d340 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 functions] are p
1d350 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 rotected..** ^Th
1d360 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
1d370 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
1d380 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
1d390 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
1d3a0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a s unprotected..*
1d3b0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 * Unprotected sq
1d3c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1d3d0 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 cts may only be
1d3e0 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 used with.** [sq
1d3f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
1d400 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ue()] and [sqlit
1d410 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d e3_bind_value()]
1d420 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
1d430 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 3_value_blob | s
1d440 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
1d450 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a e()] family of.*
1d460 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 * interfaces req
1d470 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 uire protected s
1d480 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1d490 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ects..*/.typedef
1d4a0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 struct Mem sqli
1d4b0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a te3_value;../*.*
1d4c0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
1d4d0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 Function Context
1d4e0 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d Object {H16001}
1d4f0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20200>.**.**
1d500 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 The context in w
1d510 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 hich an SQL func
1d520 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 tion executes is
1d530 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a stored in an.**
1d540 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
1d550 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 object. ^A poi
1d560 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 nter to an sqlit
1d570 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
1d580 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 t.** is always f
1d590 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
1d5a0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 o [application-d
1d5b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
1d5c0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 ions]..** The ap
1d5d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
1d5e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 d SQL function i
1d5f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
1d600 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 ll pass this.**
1d610 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 pointer through
1d620 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 into calls to [s
1d630 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
1d640 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 t | sqlite3_resu
1d650 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 lt()],.** [sqlit
1d660 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
1d670 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 text()], [sqlite
1d680 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 3_user_data()],.
1d690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
1d6a0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d ext_db_handle()]
1d6b0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 , [sqlite3_get_a
1d6c0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e uxdata()],.** an
1d6d0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 d/or [sqlite3_se
1d6e0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f t_auxdata()]..*/
1d6f0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
1d700 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
1d710 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b sqlite3_context;
1d720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1d730 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 : Binding Values
1d740 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
1d750 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d tements {H13500}
1d760 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 <S70300>.** KEY
1d770 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 WORDS: {host par
1d780 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 ameter} {host pa
1d790 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 rameters} {host
1d7a0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a parameter name}.
1d7b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 ** KEYWORDS: {SQ
1d7c0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 L parameter} {SQ
1d7d0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 L parameters} {p
1d7e0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 arameter binding
1d7f0 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 }.**.** ^(In the
1d800 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
1d810 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 ext input to [sq
1d820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1d830 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 ()] and its vari
1d840 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c ants,.** literal
1d850 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 s may be replace
1d860 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 d by a [paramete
1d870 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 r] that matches
1d880 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 one of following
1d890 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a .** templates:.*
1d8a0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
1d8b0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e > ?.** <li> ?N
1d8c0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 NN.** <li> :VVV
1d8d0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a .** <li> @VVV.*
1d8e0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 * <li> $VVV.**
1d8f0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 </ul>.**.** In t
1d900 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f he templates abo
1d910 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e ve, NNN represen
1d920 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 ts an integer li
1d930 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 teral,.** and VV
1d940 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 V represents an
1d950 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 alphanumeric ide
1d960 6e 74 69 66 65 72 2e 29 5e 20 20 5e 54 68 65 20 ntifer.)^ ^The
1d970 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a values of these.
1d980 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 ** parameters (a
1d990 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 lso called "host
1d9a0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 parameter names
1d9b0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 " or "SQL parame
1d9c0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 ters").** can be
1d9d0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 set using the s
1d9e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
1d9f0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 routines defined
1da00 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 here..**.** ^Th
1da10 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1da20 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
1da30 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1da40 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 s is always.** a
1da50 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
1da60 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
1da70 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 bject returned f
1da80 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
1da90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
1daa0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a its variants..*
1dab0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
1dac0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
1dad0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 index of the SQ
1dae0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 L parameter to b
1daf0 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c e set..** ^The l
1db00 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 eftmost SQL para
1db10 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
1db20 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 ex of 1. ^When
1db30 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a the same named.*
1db40 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 * SQL parameter
1db50 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
1db60 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 n once, second a
1db70 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a nd subsequent.**
1db80 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 occurrences hav
1db90 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 e the same index
1dba0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 as the first oc
1dbb0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 currence..** ^Th
1dbc0 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 e index for name
1dbd0 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e d parameters can
1dbe0 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 be looked up us
1dbf0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
1dc00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1dc10 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 er_index()] API
1dc20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 if desired. ^Th
1dc30 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 e index.** for "
1dc40 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 ?NNN" parameters
1dc50 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
1dc60 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e NNN..** ^The NN
1dc70 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 N value must be
1dc80 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 between 1 and th
1dc90 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 e [sqlite3_limit
1dca0 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ()].** parameter
1dcb0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [SQLITE_LIMIT_V
1dcc0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 ARIABLE_NUMBER]
1dcd0 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 (default value:
1dce0 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 999)..**.** ^The
1dcf0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
1dd00 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 is the value to
1dd10 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 bind to the para
1dd20 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 meter..**.** ^(I
1dd30 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 n those routines
1dd40 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 that have a fou
1dd50 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 rth argument, it
1dd60 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a s value is the.*
1dd70 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 * number of byte
1dd80 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 s in the paramet
1dd90 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 er. To be clear
1dda0 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 : the value is t
1ddb0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
1ddc0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 <u>bytes</u> in
1ddd0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 the value, not t
1dde0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
1ddf0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 racters.)^.** ^I
1de00 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
1de10 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 ameter is negati
1de20 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f ve, the length o
1de30 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a f the string is.
1de40 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
1de50 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 bytes up to the
1de60 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
1de70 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 inator..**.** ^T
1de80 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
1de90 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e t to sqlite3_bin
1dea0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 d_blob(), sqlite
1deb0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 3_bind_text(), a
1dec0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 nd.** sqlite3_bi
1ded0 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 nd_text16() is a
1dee0 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 destructor used
1def0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 to dispose of t
1df00 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 he BLOB or.** st
1df10 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 ring after SQLit
1df20 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 e has finished w
1df30 69 74 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20 ith it. ^If the
1df40 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 fifth argument i
1df50 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c s.** the special
1df60 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 value [SQLITE_S
1df70 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c TATIC], then SQL
1df80 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 ite assumes that
1df90 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 the.** informat
1dfa0 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 ion is in static
1dfb0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 , unmanaged spac
1dfc0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e e and does not n
1dfd0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e eed to be freed.
1dfe0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 .** ^If the fift
1dff0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 h argument has t
1e000 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 he value [SQLITE
1e010 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 _TRANSIENT], the
1e020 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 n.** SQLite make
1e030 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 s its own privat
1e040 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 e copy of the da
1e050 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 ta immediately,
1e060 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 before.** the sq
1e070 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
1e080 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a outine returns..
1e090 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1e0a0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
1e0b0 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 () routine binds
1e0c0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 a BLOB of lengt
1e0d0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 h N that.** is f
1e0e0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 illed with zeroe
1e0f0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 s. ^A zeroblob
1e100 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f uses a fixed amo
1e110 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a unt of memory.**
1e120 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 (just an intege
1e130 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 r to hold its si
1e140 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 ze) while it is
1e150 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e being processed.
1e160 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 .** Zeroblobs ar
1e170 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 e intended to se
1e180 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 rve as placehold
1e190 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 ers for BLOBs wh
1e1a0 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 ose.** content i
1e1b0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 s later written
1e1c0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
1e1d0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 3_blob_open | in
1e1e0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 cremental BLOB I
1e1f0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a /O] routines..**
1e200 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c ^A negative val
1e210 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 ue for the zerob
1e220 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 lob results in a
1e230 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
1e240 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 B..**.** ^If any
1e250 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
1e260 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1e270 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 s are called wit
1e280 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
1e290 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 .** for the [pre
1e2a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1e2b0 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 or with a prepa
1e2c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f red statement fo
1e2d0 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 r which.** [sqli
1e2e0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
1e2f0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 been called more
1e300 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b recently than [
1e310 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
1e320 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 ,.** then the ca
1e330 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b ll will return [
1e340 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 SQLITE_MISUSE].
1e350 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f If any sqlite3_
1e360 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 bind_().** routi
1e370 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b ne is passed a [
1e380 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1e390 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 nt] that has bee
1e3a0 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 n finalized, the
1e3b0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e .** result is un
1e3c0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
1e3d0 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a ably harmful..**
1e3e0 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 .** ^Bindings ar
1e3f0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 e not cleared by
1e400 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 the [sqlite3_re
1e410 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a set()] routine..
1e420 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 ** ^Unbound para
1e430 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 meters are inter
1e440 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a preted as NULL..
1e450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1e460 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e e3_bind_* routin
1e470 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 es return [SQLIT
1e480 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 E_OK] on success
1e490 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 or an.** [error
1e4a0 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 code] if anythi
1e4b0 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a ng goes wrong..*
1e4c0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 * ^[SQLITE_RANGE
1e4d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
1e4e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a the parameter.*
1e4f0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f * index is out o
1e500 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 f range. ^[SQLI
1e510 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 TE_NOMEM] is ret
1e520 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 urned if malloc(
1e530 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 ) fails..**.** S
1e540 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
1e550 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1e560 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 _count()],.** [s
1e570 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1e580 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 meter_name()], a
1e590 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 nd [sqlite3_bind
1e5a0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
1e5b0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
1e5c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 te3_bind_blob(sq
1e5d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1e5e0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
1e5f0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f nt n, void(*)(vo
1e600 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
1e610 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 e3_bind_double(s
1e620 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1e630 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 t, double);.int
1e640 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 sqlite3_bind_int
1e650 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1e660 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 int, int);.int s
1e670 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 qlite3_bind_int6
1e680 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
1e690 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e int, sqlite3_in
1e6a0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 t64);.int sqlite
1e6b0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 3_bind_null(sqli
1e6c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
1e6d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
1e6e0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 d_text(sqlite3_s
1e6f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
1e700 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 char*, int n, v
1e710 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
1e720 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
1e730 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
1e740 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
1e750 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
1e760 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
1e770 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1e780 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
1e790 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
1e7a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
1e7b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
1e7c0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 d_zeroblob(sqlit
1e7d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 e3_stmt*, int, i
1e7e0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt n);../*.** CA
1e7f0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f PI3REF: Number O
1e800 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 f SQL Parameters
1e810 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
1e820 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 tine can be used
1e830 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d to find the num
1e840 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 ber of [SQL para
1e850 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 meters].** in a
1e860 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1e870 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d ent]. SQL param
1e880 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 eters are tokens
1e890 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 of the.** form
1e8a0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 "?", "?NNN", ":A
1e8b0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 AA", "$AAA", or
1e8c0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 "@AAA" that serv
1e8d0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c e as.** placehol
1e8e0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 ders for values
1e8f0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 that are [sqlite
1e900 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 3_bind_blob | bo
1e910 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 und].** to the p
1e920 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c arameters at a l
1e930 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a ater time..**.**
1e940 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ^(This routine
1e950 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 actually returns
1e960 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
1e970 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 e largest (right
1e980 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 most).** paramet
1e990 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d er. For all form
1e9a0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 s except ?NNN, t
1e9b0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 his will corresp
1e9c0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 ond to the.** nu
1e9d0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 mber of unique p
1e9e0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 arameters. If p
1e9f0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
1ea00 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 ?NNN form are u
1ea10 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 sed,.** there ma
1ea20 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 y be gaps in the
1ea30 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 list.)^.**.** S
1ea40 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
1ea50 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
1ea60 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
1ea70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1ea80 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c rameter_name()],
1ea90 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
1eaa0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1eab0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 index()]..*/.int
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 63 6f 75 6e 74 28 73 71 rameter_count(sq
1eae0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
1eaf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
1eb00 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 ame Of A Host Pa
1eb10 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 rameter.**.** ^T
1eb20 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1eb30 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 parameter_name(P
1eb40 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 ,N) interface re
1eb50 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d turns.** the nam
1eb60 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 e of the N-th [S
1eb70 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e QL parameter] in
1eb80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
1eb90 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 tatement] P..**
1eba0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 ^(SQL parameters
1ebb0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e of the form "?N
1ebc0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 NN" or ":AAA" or
1ebd0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 "@AAA" or "$AAA
1ebe0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 ".** have a name
1ebf0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 which is the st
1ec00 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 ring "?NNN" or "
1ec10 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 :AAA" or "@AAA"
1ec20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 or "$AAA".** res
1ec30 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e pectively..** In
1ec40 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
1ec50 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 e initial ":" or
1ec60 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 "$" or "@" or "
1ec70 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 ?".** is include
1ec80 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
1ec90 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 name.)^.** ^Par
1eca0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
1ecb0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 orm "?" without
1ecc0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 a following inte
1ecd0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 ger have no name
1ece0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f .** and are also
1ecf0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 referred to as
1ed00 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 "nameless" or "a
1ed10 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 nonymous paramet
1ed20 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ers"..**.** ^The
1ed30 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 first host para
1ed40 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
1ed50 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a ex of 1, not 0..
1ed60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 **.** ^If the va
1ed70 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 lue N is out of
1ed80 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 range or if the
1ed90 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 N-th parameter i
1eda0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 s.** nameless, t
1edb0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 hen NULL is retu
1edc0 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 rned. ^The retu
1edd0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a rned string is.*
1ede0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d * always in UTF-
1edf0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 8 encoding even
1ee00 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 if the named par
1ee10 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 ameter was.** or
1ee20 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 iginally specifi
1ee30 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 ed as UTF-16 in
1ee40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1ee50 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 16()] or.** [sql
1ee60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1ee70 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 2()]..**.** See
1ee80 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
1ee90 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
1eea0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
1eeb0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
1eec0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 eter_count()], a
1eed0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
1eee0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
1eef0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 dex()]..*/.const
1ef00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 char *sqlite3_b
1ef10 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
1ef20 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
1ef30 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , int);../*.** C
1ef40 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f API3REF: Index O
1ef50 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 f A Parameter Wi
1ef60 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a th A Given Name.
1ef70 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 **.** ^Return th
1ef80 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 e index of an SQ
1ef90 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 L parameter give
1efa0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 n its name. ^Th
1efb0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 e.** index value
1efc0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 returned is sui
1efd0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 table for use as
1efe0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 the second.** p
1eff0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
1f000 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
1f010 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 qlite3_bind()].
1f020 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 ^A zero.** is r
1f030 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 eturned if no ma
1f040 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 tching parameter
1f050 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 is found. ^The
1f060 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 parameter.** na
1f070 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e me must be given
1f080 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 in UTF-8 even i
1f090 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 f the original s
1f0a0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 tatement.** was
1f0b0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 prepared from UT
1f0c0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 F-16 text using
1f0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f0e0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 16_v2()]..**.**
1f0f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
1f100 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
1f110 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a ite3_bind()],.**
1f120 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1f130 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 arameter_count()
1f140 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
1f150 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1f160 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 r_index()]..*/.i
1f170 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1f180 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
1f190 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 sqlite3_stmt*, c
1f1a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
1f1b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1f1c0 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 EF: Reset All Bi
1f1d0 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 ndings On A Prep
1f1e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a ared Statement.*
1f1f0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 *.** ^Contrary t
1f200 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 o the intuition
1f210 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 of many, [sqlite
1f220 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 3_reset()] does
1f230 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 not reset.** the
1f240 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
1f250 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 lob | bindings]
1f260 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
1f270 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 tatement]..** ^U
1f280 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 se this routine
1f290 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 to reset all hos
1f2a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
1f2b0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c NULL..*/.int sql
1f2c0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 ite3_clear_bindi
1f2d0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
1f2e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1f2f0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 REF: Number Of C
1f300 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 olumns In A Resu
1f310 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 lt Set.**.** ^Re
1f320 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 turn the number
1f330 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
1f340 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 e result set ret
1f350 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 urned by the.**
1f360 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1f370 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 ent]. ^This rout
1f380 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 ine returns 0 if
1f390 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c pStmt is an SQL
1f3a0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 .** statement th
1f3b0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 at does not retu
1f3c0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 rn data (for exa
1f3d0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d mple an [UPDATE]
1f3e0 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 )..*/.int sqlite
1f3f0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
1f400 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
1f410 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
1f420 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
1f430 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
1f440 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 et.**.** ^These
1f450 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1f460 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 the name assigne
1f470 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 d to a particula
1f480 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 r column.** in t
1f490 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 he result set of
1f4a0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
1f4b0 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c ement. ^The sql
1f4c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1f4d0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
1f4e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1f4f0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
1f500 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
1f510 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 ing.** and sqlit
1f520 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
1f530 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
1f540 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
1f550 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
1f560 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
1f570 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
1f580 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 r is the [prepar
1f590 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
1f5a0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
1f5b0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 the [SELECT] st
1f5c0 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 atement. ^The se
1f5d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
1f5e0 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 s the.** column
1f5f0 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 number. ^The le
1f600 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 ftmost column is
1f610 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a number 0..**.**
1f620 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
1f630 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 tring pointer is
1f640 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 valid until eit
1f650 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 her the [prepare
1f660 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
1f670 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 is destroyed by
1f680 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
1f690 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 e()] or until th
1f6a0 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a e next call to.*
1f6b0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
1f6c0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 _name() or sqlit
1f6d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
1f6e0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 () on the same c
1f6f0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 olumn..**.** ^If
1f700 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1f710 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 ) fails during t
1f720 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 he processing of
1f730 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a either routine.
1f740 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 ** (for example
1f750 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 during a convers
1f760 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 ion from UTF-8 t
1f770 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 o UTF-16) then a
1f780 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
1f790 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
1f7a0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 .** ^The name of
1f7b0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e a result column
1f7c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
1f7d0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 the "AS" clause
1f7e0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c for.** that col
1f7f0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 umn, if there is
1f800 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 an AS clause.
1f810 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 If there is no A
1f820 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e S clause.** then
1f830 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1f840 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 column is unspe
1f850 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 cified and may c
1f860 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e hange from.** on
1f870 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c e release of SQL
1f880 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e ite to the next.
1f890 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
1f8a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
1f8b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
1f8c0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 *, int N);.const
1f8d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
1f8e0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c olumn_name16(sql
1f8f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
1f900 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 N);../*.** CAPI3
1f910 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 REF: Source Of D
1f920 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 ata In A Query R
1f930 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 esult.**.** ^The
1f940 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 se routines prov
1f950 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 ide a means to d
1f960 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f etermine what co
1f970 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 lumn of what.**
1f980 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 table in which d
1f990 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 atabase a result
1f9a0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 of a [SELECT] s
1f9b0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 tatement comes f
1f9c0 72 6f 6d 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d rom..** ^The nam
1f9d0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
1f9e0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f e or table or co
1f9f0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 lumn can be retu
1fa00 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 rned as.** eithe
1fa10 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 r a UTF-8 or UTF
1fa20 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
1fa30 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 e _database_ rou
1fa40 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 tines return.**
1fa50 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
1fa60 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 e, the _table_ r
1fa70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
1fa80 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 he table name, a
1fa90 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e nd.** the origin
1faa0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
1fab0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d n the column nam
1fac0 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 e..** ^The retur
1fad0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 ned string is va
1fae0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 lid until the [p
1faf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1fb00 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a t] is destroyed.
1fb10 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
1fb20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
1fb30 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 until the same
1fb40 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 information is r
1fb50 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 equested.** agai
1fb60 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 n in a different
1fb70 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a encoding..**.**
1fb80 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 ^The names retu
1fb90 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 rned are the ori
1fba0 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 ginal un-aliased
1fbb0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a names of the.**
1fbc0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
1fbd0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a , and column..**
1fbe0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
1fbf0 72 67 75 6d 65 6e 74 20 74 68 65 73 65 20 69 6e rgument these in
1fc00 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 terfaces is a [p
1fc10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1fc20 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 t]..** ^These fu
1fc30 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 nctions return i
1fc40 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
1fc50 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
1fc60 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
1fc70 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
1fc80 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
1fc90 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
1fca0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c ument..** ^The l
1fcb0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 eft-most column
1fcc0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 is column 0 for
1fcd0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 2e these interface.
1fce0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e .**.** ^If the N
1fcf0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e th column return
1fd00 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d ed by the statem
1fd10 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 ent is an expres
1fd20 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 sion or.** subqu
1fd30 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ery and is not a
1fd40 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 column value, t
1fd50 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 hen all of these
1fd60 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
1fd70 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 n.** NULL. ^The
1fd80 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 se routine might
1fd90 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c also return NUL
1fda0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c L if a memory al
1fdb0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a location error.*
1fdc0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 * occurs. ^Othe
1fdd0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 rwise, they retu
1fde0 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 rn the name of t
1fdf0 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 he attached data
1fe00 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 6f base, table.** o
1fe10 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 r column that qu
1fe20 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
1fe30 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
1fe40 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 from..**.** ^As
1fe50 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
1fe60 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
1fe70 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 e postfixed with
1fe80 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 "16" return.**
1fe90 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 UTF-16 encoded s
1fea0 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 trings, the othe
1feb0 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 r functions retu
1fec0 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 rn UTF-8..**.**
1fed0 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 ^These APIs are
1fee0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 only available i
1fef0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 f the library wa
1ff00 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
1ff10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 the.** [SQLITE_E
1ff20 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 NABLE_COLUMN_MET
1ff30 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 ADATA] C-preproc
1ff40 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 essor symbol def
1ff50 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ined..**.** If t
1ff60 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
1ff70 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
1ff80 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ore of these rou
1ff90 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 tines against th
1ffa0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 e same.** prepar
1ffb0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ed statement and
1ffc0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 column at the s
1ffd0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
1ffe0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a e results are.**
1fff0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
20000 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 * If two or more
20010 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e threads call on
20020 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 e or more.** [sq
20030 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
20040 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c abase_name | col
20050 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 umn metadata int
20060 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 erfaces].** for
20070 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 the same [prepar
20080 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e ed statement] an
20090 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a d result column.
200a0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ** at the same t
200b0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
200c0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
200d0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 ed..*/.const cha
200e0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
200f0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 n_database_name(
20100 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
20110 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
20120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
20130 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 atabase_name16(s
20140 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
20150 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
20160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
20170 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ble_name(sqlite3
20180 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
20190 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
201a0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
201b0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
201c0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 t*,int);.const c
201d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
201e0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 umn_origin_name(
201f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
20200 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
20210 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
20220 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c rigin_name16(sql
20230 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
20240 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20250 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 : Declared Datat
20260 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 ype Of A Query R
20270 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 esult.**.** ^(Th
20280 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
20290 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 r is a [prepared
202a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
202b0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e If this statemen
202c0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 t is a [SELECT]
202d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 statement and th
202e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
202f0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 the.** returned
20300 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 result set of th
20310 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 at [SELECT] is a
20320 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e table column (n
20330 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 ot an.** express
20340 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 ion or subquery)
20350 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 then the declar
20360 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 ed type of the t
20370 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 able.** column i
20380 73 20 72 65 74 75 72 6e 65 64 2e 29 20 20 5e 49 s returned.) ^I
20390 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
203a0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
203b0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 et is an.** expr
203c0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
203d0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 ry, then a NULL
203e0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
203f0 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ned..** ^The ret
20400 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
20410 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 always UTF-8 enc
20420 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f oded..**.** ^(Fo
20430 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e r example, given
20440 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 the database sc
20450 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 hema:.**.** CREA
20460 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 TE TABLE t1(c1 V
20470 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 ARIANT);.**.** a
20480 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 nd the following
20490 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
204a0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a compiled:.**.**
204b0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 SELECT c1 + 1,
204c0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a c1 FROM t1;.**.*
204d0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 * this routine w
204e0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 ould return the
204f0 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 string "VARIANT"
20500 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 for the second
20510 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e result.** column
20520 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e (i==1), and a N
20530 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 ULL pointer for
20540 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 the first result
20550 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 column (i==0).)
20560 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ^.**.** ^SQLite
20570 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e uses dynamic run
20580 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e -time typing. ^
20590 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 So just because
205a0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 a column.** is d
205b0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 eclared to conta
205c0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 in a particular
205d0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 type does not me
205e0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 an that the.** d
205f0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 ata stored in th
20600 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 at column is of
20610 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
20620 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a e. SQLite is.**
20630 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c strongly typed,
20640 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 but the typing
20650 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 is dynamic not s
20660 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a tatic. ^Type.**
20670 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 is associated w
20680 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 ith individual v
20690 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 alues, not with
206a0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a the containers.*
206b0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 * used to hold t
206c0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a hose values..*/.
206d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
206e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
206f0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
20700 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f *,int);.const vo
20710 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
20720 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 mn_decltype16(sq
20730 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
20740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
20750 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 F: Evaluate An S
20760 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a QL Statement.**.
20770 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 ** After a [prep
20780 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
20790 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 has been prepare
207a0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a d using either.*
207b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
207c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
207d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
207e0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 2()] or one of t
207f0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
20800 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 erfaces [sqlite3
20810 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b _prepare()] or [
20820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
20830 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 6()], this funct
20840 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 ion.** must be c
20850 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 alled one or mor
20860 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 e times to evalu
20870 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e ate the statemen
20880 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 t..**.** The det
20890 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 ails of the beha
208a0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 vior of the sqli
208b0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 te3_step() inter
208c0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f face depend.** o
208d0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 n whether the st
208e0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 atement was prep
208f0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e ared using the n
20900 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 ewer "v2" interf
20910 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ace.** [sqlite3_
20920 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
20930 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
20940 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 re16_v2()] or th
20950 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a e older legacy.*
20960 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c * interface [sql
20970 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
20980 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
20990 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 pare16()]. The
209a0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 use of the.** ne
209b0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 w "v2" interface
209c0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
209d0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 for new applicat
209e0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 ions but the leg
209f0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
20a00 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 will continue t
20a10 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a o be supported..
20a20 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 **.** ^In the le
20a30 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
20a40 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
20a50 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 will be either
20a60 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a [SQLITE_BUSY],.*
20a70 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c * [SQLITE_DONE],
20a80 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b [SQLITE_ROW], [
20a90 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f SQLITE_ERROR], o
20aa0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 r [SQLITE_MISUSE
20ab0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 ]..** ^With the
20ac0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 "v2" interface,
20ad0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 any of the other
20ae0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 [result codes]
20af0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
20b00 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 result codes] mi
20b10 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 ght be returned
20b20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e as well..**.** ^
20b30 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 [SQLITE_BUSY] me
20b40 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 ans that the dat
20b50 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 abase engine was
20b60 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 unable to acqui
20b70 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 re the.** databa
20b80 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 se locks it need
20b90 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e s to do its job.
20ba0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d ^If the statem
20bb0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 ent is a [COMMIT
20bc0 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f ].** or occurs o
20bd0 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 utside of an exp
20be0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
20bf0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 n, then you can
20c00 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 retry the.** sta
20c10 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 tement. If the
20c20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 statement is not
20c30 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 a [COMMIT] and
20c40 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a occurs within a.
20c50 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e ** explicit tran
20c60 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 saction then you
20c70 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b should rollback
20c80 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
20c90 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 before.** conti
20ca0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 nuing..**.** ^[S
20cb0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e QLITE_DONE] mean
20cc0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 s that the state
20cd0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 ment has finishe
20ce0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 d executing.** s
20cf0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 uccessfully. sq
20d00 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
20d10 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
20d20 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 d again on this
20d30 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 virtual.** machi
20d40 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 ne without first
20d50 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
20d60 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 3_reset()] to re
20d70 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a set the virtual.
20d80 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 ** machine back
20d90 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 to its initial s
20da0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 tate..**.** ^If
20db0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
20dc0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 t being executed
20dd0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 returns any dat
20de0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f a, then [SQLITE_
20df0 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 ROW].** is retur
20e00 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 ned each time a
20e10 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 new row of data
20e20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f is ready for pro
20e30 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a cessing by the.*
20e40 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 * caller. The va
20e50 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 lues may be acce
20e60 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b ssed using the [
20e70 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
20e80 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c nctions]..** sql
20e90 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 ite3_step() is c
20ea0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 alled again to r
20eb0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 etrieve the next
20ec0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a row of data..**
20ed0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 .** ^[SQLITE_ERR
20ee0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 OR] means that a
20ef0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 run-time error
20f00 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 (such as a const
20f10 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 raint.** violati
20f20 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 on) has occurred
20f30 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
20f40 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
20f50 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a called again on.
20f60 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 ** the VM. More
20f70 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 information may
20f80 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c be found by call
20f90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 ing [sqlite3_err
20fa0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 msg()]..** ^With
20fb0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
20fc0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 rface, a more sp
20fd0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
20fe0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a e (for example,.
20ff0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 ** [SQLITE_INTER
21000 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 RUPT], [SQLITE_S
21010 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f CHEMA], [SQLITE_
21020 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f CORRUPT], and so
21030 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 forth).** can b
21040 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 e obtained by ca
21050 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
21060 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a eset()] on the.*
21070 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
21080 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 ement]. ^In the
21090 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
210a0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 .** the more spe
210b0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
210c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 is returned dir
210d0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 ectly by sqlite3
210e0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b _step()..**.** [
210f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d SQLITE_MISUSE] m
21100 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 eans that the th
21110 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 is routine was c
21120 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 alled inappropri
21130 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 ately..** Perhap
21140 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 s it was called
21150 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
21160 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
21170 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 as.** already be
21180 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 en [sqlite3_fina
21190 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 lize | finalized
211a0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 ] or on one that
211b0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 had.** previous
211c0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c ly returned [SQL
211d0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 ITE_ERROR] or [S
211e0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 QLITE_DONE]. Or
211f0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 it could.** be
21200 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
21210 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
21220 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 connection is be
21230 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 ing used by two
21240 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 or.** more threa
21250 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d ds at the same m
21260 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a oment in time..*
21270 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e *.** <b>Goofy In
21280 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f terface Alert:</
21290 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 b> In the legacy
212a0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 interface, the
212b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a sqlite3_step().*
212c0 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 * API always ret
212d0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 urns a generic e
212e0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 rror code, [SQLI
212f0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f TE_ERROR], follo
21300 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f wing any.** erro
21310 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 r other than [SQ
21320 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b LITE_BUSY] and [
21330 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 SQLITE_MISUSE].
21340 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a You must call.*
21350 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
21360 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
21370 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f finalize()] in o
21380 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 rder to find one
21390 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 of the.** speci
213a0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 fic [error codes
213b0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 ] that better de
213c0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f scribes the erro
213d0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 r..** We admit t
213e0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f hat this is a go
213f0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 ofy design. The
21400 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 problem has bee
21410 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 n fixed.** with
21420 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
21430 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 ce. If you prep
21440 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 are all of your
21450 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
21460 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b * using either [
21470 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
21480 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
21490 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
214a0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 ] instead.** of
214b0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 the legacy [sqli
214c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
214d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
214e0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 are16()] interfa
214f0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ces,.** then the
21500 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b more specific [
21510 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 error codes] are
21520 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
21530 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ly.** by sqlite3
21540 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 _step(). The us
21550 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e e of the "v2" in
21560 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d terface is recom
21570 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 mended..*/.int s
21580 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 qlite3_step(sqli
21590 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
215a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
215b0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
215c0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a n a result set.*
215d0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74 68 *.** ^Returns th
215e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 e number of valu
215f0 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e es in the curren
21600 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
21610 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 ult set..*/.int
21620 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
21630 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 nt(sqlite3_stmt
21640 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
21650 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d CAPI3REF: Fundam
21660 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a ental Datatypes.
21670 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c ** KEYWORDS: SQL
21680 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b ITE_TEXT.**.** {
21690 48 31 30 32 36 36 7d 20 45 76 65 72 79 20 76 61 H10266} Every va
216a0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 lue in SQLite ha
216b0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 s one of five fu
216c0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 ndamental dataty
216d0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a pes:.**.** <ul>.
216e0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 ** <li> 64-bit s
216f0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
21700 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 <li> 64-bit IEE
21710 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 E floating point
21720 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 number.** <li>
21730 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 string.** <li> B
21740 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c LOB.** <li> NULL
21750 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a .** </ul> {END}.
21760 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
21770 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 tants are codes
21780 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 for each of thos
21790 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e e types..**.** N
217a0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ote that the SQL
217b0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e ITE_TEXT constan
217c0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 t was also used
217d0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f in SQLite versio
217e0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d n 2.** for a com
217f0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e pletely differen
21800 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 t meaning. Soft
21810 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 ware that links
21820 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 against both.**
21830 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 SQLite version 2
21840 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 and SQLite vers
21850 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 ion 3 should use
21860 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e SQLITE3_TEXT, n
21870 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 ot.** SQLITE_TEX
21880 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 T..*/.#define SQ
21890 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a LITE_INTEGER 1.
218a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
218b0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e LOAT 2.#defin
218c0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 e SQLITE_BLOB
218d0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
218e0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 TE_NULL 5.#i
218f0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 fdef SQLITE_TEXT
21900 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
21910 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 TEXT.#else.# def
21920 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 ine SQLITE_TEXT
21930 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 3.#endif.#de
21940 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 fine SQLITE3_TEX
21950 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 T 3../*.** C
21960 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
21970 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 Values From A Qu
21980 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ery.** KEYWORDS:
21990 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 {column access
219a0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a functions}.**.**
219b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
219c0 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 form the "result
219d0 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e set" interface.
219e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
219f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e utines return in
21a00 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
21a10 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 a single column
21a20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a of the current.*
21a30 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 * result row of
21a40 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 a query. ^In ev
21a50 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 ery case the fir
21a60 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
21a70 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 pointer.** to t
21a80 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
21a90 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 tement] that is
21aa0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 being evaluated
21ab0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 (the [sqlite3_st
21ac0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 mt*].** that was
21ad0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b returned from [
21ae0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
21af0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 v2()] or one of
21b00 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a its variants).**
21b10 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
21b20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
21b30 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c index of the col
21b40 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e umn for which in
21b50 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f formation.** sho
21b60 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e uld be returned.
21b70 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 ^The leftmost c
21b80 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 olumn of the res
21b90 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 ult set has the
21ba0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 index 0..** ^The
21bb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
21bc0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
21bd0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e can be determin
21be0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c ed using.** [sql
21bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
21c00 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 t()]..**.** If t
21c10 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
21c20 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e does not curren
21c30 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 tly point to a v
21c40 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 alid row, or if
21c50 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e the.** column in
21c60 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
21c70 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 nge, the result
21c80 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
21c90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
21ca0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c may only be call
21cb0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 ed when the most
21cc0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a recent call to.
21cd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
21ce0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 ()] has returned
21cf0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e [SQLITE_ROW] an
21d00 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 d neither.** [sq
21d10 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e lite3_reset()] n
21d20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
21d30 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 lize()] have bee
21d40 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 n called subsequ
21d50 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 ently..** If any
21d60 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
21d70 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 es are called af
21d80 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ter [sqlite3_res
21d90 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
21da0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
21db0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 or after [sqlit
21dc0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 e3_step()] has r
21dd0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 eturned.** somet
21de0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 hing other than
21df0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 [SQLITE_ROW], th
21e00 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
21e10 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b defined..** If [
21e20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
21e30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
21e40 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
21e50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 _finalize()].**
21e60 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 are called from
21e70 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 a different thre
21e80 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 ad while any of
21e90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
21ea0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 * are pending, t
21eb0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
21ec0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
21ed0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
21ee0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 3_column_type()
21ef0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
21f00 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 the.** [SQLITE_I
21f10 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 NTEGER | datatyp
21f20 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 e code] for the
21f30 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 initial data typ
21f40 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 e.** of the resu
21f50 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 lt column. ^The
21f60 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 returned value
21f70 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 is one of [SQLIT
21f80 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b E_INTEGER],.** [
21f90 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b SQLITE_FLOAT], [
21fa0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 SQLITE_TEXT], [S
21fb0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 QLITE_BLOB], or
21fc0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 [SQLITE_NULL].
21fd0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 The value.** ret
21fe0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
21ff0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
22000 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 s only meaningfu
22010 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 l if no type.**
22020 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 conversions have
22030 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 occurred as des
22040 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 cribed below. A
22050 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 fter a type conv
22060 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 ersion,.** the v
22070 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
22080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
22090 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 type() is undefi
220a0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 ned. Future.**
220b0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
220c0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 te may change th
220d0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 e behavior of sq
220e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
220f0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 e().** following
22100 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
22110 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 on..**.** ^If th
22120 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c e result is a BL
22130 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 OB or UTF-8 stri
22140 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 ng then the sqli
22150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
22160 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 ().** routine re
22170 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
22180 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
22190 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 t BLOB or string
221a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
221b0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 ult is a UTF-16
221c0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c string, then sql
221d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
221e0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 s() converts.**
221f0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 the string to UT
22200 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 F-8 and then ret
22210 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
22220 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 of bytes..** ^If
22230 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
22240 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 numeric value t
22250 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
22260 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a mn_bytes() uses.
22270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 ** [sqlite3_snpr
22280 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 intf()] to conve
22290 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f rt that value to
222a0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 a UTF-8 string
222b0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 and returns.** t
222c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
222d0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e es in that strin
222e0 67 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 g..** ^The value
222f0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e returned does n
22300 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a ot include the z
22310 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 ero terminator a
22320 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 t the end.** of
22330 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f the string. ^Fo
22340 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 r clarity: the v
22350 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 alue returned is
22360 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
22370 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 * bytes in the s
22380 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e tring, not the n
22390 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 umber of charact
223a0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 ers..**.** ^Stri
223b0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
223c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
223d0 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ext() and sqlite
223e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
223f0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 ),.** even empty
22400 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c strings, are al
22410 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e ways zero termin
22420 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 ated. ^The retu
22430 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d rn.** value from
22440 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
22450 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 blob() for a zer
22460 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 o-length BLOB is
22470 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a an arbitrary.**
22480 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 pointer, possib
22490 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 ly even a NULL p
224a0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
224b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
224c0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 n_bytes16() rout
224d0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
224e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
224f0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 _bytes().** but
22500 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c leaves the resul
22510 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e t in UTF-16 in n
22520 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
22530 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d instead of UTF-
22540 38 2e 0a 2a 2a 20 5e 54 68 65 20 7a 65 72 6f 20 8..** ^The zero
22550 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f terminator is no
22560 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 t included in th
22570 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 is count..**.**
22580 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 ^The object retu
22590 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
225a0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
225b0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f is an.** [unpro
225c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
225d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 alue] object. A
225e0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
225f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
22600 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 ct.** may only b
22610 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c e used with [sql
22620 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
22630 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
22640 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e result_value()].
22650 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 .** If the [unpr
22660 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
22670 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 value] object re
22680 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
22690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
226a0 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e ue()] is used in
226b0 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 any other way,
226c0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a including calls.
226d0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c ** to routines l
226e0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c ike [sqlite3_val
226f0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 ue_int()], [sqli
22700 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
22710 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
22720 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 3_value_bytes()]
22730 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
22740 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
22750 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
22760 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 utines attempt t
22770 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 o convert the va
22780 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 lue where approp
22790 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 riate. ^For.**
227a0 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 example, if the
227b0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
227c0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 ntation is FLOAT
227d0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 and a text resu
227e0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 lt.** is request
227f0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 ed, [sqlite3_snp
22800 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 rintf()] is used
22810 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 internally to p
22820 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f erform the.** co
22830 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 nversion automat
22840 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 ically. ^(The f
22850 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 ollowing table d
22860 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 etails the conve
22870 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 rsions.** that a
22880 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a re applied:.**.*
22890 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a * <blockquote>.*
228a0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
228b0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
228c0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 Internal<br>Typ
228d0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 e <th> Requested
228e0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 <br>Type <th> C
228f0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 onversion.**.**
22900 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
22910 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
22920 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
22930 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
22940 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f ULL <td> FLO
22950 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c AT <td> Resul
22960 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e t is 0.0.** <tr>
22970 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
22980 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
22990 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c > Result is NULL
229a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
229b0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
229c0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
229d0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c > Result is NULL
229e0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
229f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
22a00 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
22a10 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 > Convert from i
22a20 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a nteger to float.
22a30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
22a40 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 GER <td> TEXT
22a50 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
22a60 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
22a70 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c integer.** <tr><
22a80 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
22a90 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
22aa0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 Same as INTEGER
22ab0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
22ac0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
22ad0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
22ae0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f Convert from flo
22af0 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a at to integer.**
22b00 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
22b10 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
22b20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
22b30 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c dering of the fl
22b40 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
22b50 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
22b60 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d BLOB <td> Sam
22b70 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 e as FLOAT->TEXT
22b80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
22b90 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 XT <td> INTEG
22ba0 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 ER <td> Use at
22bb0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
22bc0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 TEXT <td>
22bd0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 FLOAT <td> Us
22be0 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e e atof().** <tr>
22bf0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
22c00 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
22c10 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c > No change.** <
22c20 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
22c30 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
22c40 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 <td> Convert to
22c50 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 TEXT then use at
22c60 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
22c70 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
22c80 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f FLOAT <td> Co
22c90 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 nvert to TEXT th
22ca0 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a en use atof().**
22cb0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
22cc0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
22cd0 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 <td> Add a zer
22ce0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 o terminator if
22cf0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c needed.** </tabl
22d00 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f e>.** </blockquo
22d10 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 te>)^.**.** The
22d20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 table above make
22d30 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 s reference to s
22d40 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
22d50 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 y functions atoi
22d60 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 ().** and atof()
22d70 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e . SQLite does n
22d80 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 ot really use th
22d90 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 ese functions.
22da0 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 It has its.** ow
22db0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 n equivalent int
22dc0 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 ernal routines.
22dd0 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 The atoi() and
22de0 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 atof() names are
22df0 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 .** used in the
22e00 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 table for brevit
22e10 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 y and because th
22e20 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 ey are familiar
22e30 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f to most.** C pro
22e40 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 grammers..**.**
22e50 5e 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 ^Note that when
22e60 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 type conversions
22e70 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 occur, pointers
22e80 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 returned by pri
22e90 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 or.** calls to s
22ea0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
22eb0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f ob(), sqlite3_co
22ec0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 lumn_text(), and
22ed0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 /or.** sqlite3_c
22ee0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d olumn_text16() m
22ef0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 ay be invalidate
22f00 64 2e 0a 2a 2a 20 5e 28 54 79 70 65 20 63 6f 6e d..** ^(Type con
22f10 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 versions and poi
22f20 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f nter invalidatio
22f30 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a ns might occur.*
22f40 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 * in the followi
22f50 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 ng cases:.**.**
22f60 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
22f70 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
22f80 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 is a BLOB and s
22f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
22fa0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 xt() or.**
22fb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
22fc0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
22fd0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 d. A zero-termi
22fe0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 nator might.**
22ff0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 need to be a
23000 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 dded to the stri
23010 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e ng.</li>.** <li>
23020 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
23030 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 tent is UTF-8 te
23040 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
23050 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
23060 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
23070 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
23080 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
23090 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
230a0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
230b0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c to UTF-16.<
230c0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
230d0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
230e0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 is UTF-16 text
230f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
23100 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
23110 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
23120 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 lumn_text() is c
23130 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 alled. The cont
23140 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ent must be conv
23150 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f erted.** to
23160 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-8.</li>.**
23170 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 </ul>)^.**.** ^C
23180 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 onversions betwe
23190 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 en UTF-16be and
231a0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 UTF-16le are alw
231b0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 ays done in plac
231c0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 e and do.** not
231d0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 invalidate a pri
231e0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 or pointer, thou
231f0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 gh of course the
23200 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
23210 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 buffer.** that t
23220 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 he prior pointer
23230 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 points to will
23240 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 have been modifi
23250 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 ed. Other kinds
23260 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f .** of conversio
23270 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c n are done in pl
23280 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 ace when it is p
23290 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d ossible, but som
232a0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 etimes they.** a
232b0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 re not possible
232c0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 and in those cas
232d0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 es prior pointer
232e0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 s are invalidate
232f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 d..**.** ^(The s
23300 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 afest and easies
23310 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f t to remember po
23320 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b licy is to invok
23330 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 e these routines
23340 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 .** in one of th
23350 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 e following ways
23360 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
23370 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
23380 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f umn_text() follo
23390 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
233a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c olumn_bytes()</l
233b0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 i>.** <li>sqlit
233c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
233d0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
233e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
233f0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 s()</li>.** <li
23400 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
23410 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 text16() followe
23420 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
23430 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c umn_bytes16()</l
23440 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a i>.** </ul>)^.**
23450 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
23460 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 ds, you should c
23470 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 all sqlite3_colu
23480 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 mn_text(),.** sq
23490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
234a0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f b(), or sqlite3_
234b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
234c0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 first to force t
234d0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 he result.** int
234e0 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f o the desired fo
234f0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b rmat, then invok
23500 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
23510 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 _bytes() or.** s
23520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
23530 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 tes16() to find
23540 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
23550 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 result. Do not
23560 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 mix calls.** to
23570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
23580 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
23590 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 _column_blob() w
235a0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ith calls to.**
235b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
235c0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f ytes16(), and do
235d0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 not mix calls t
235e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
235f0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 _text16().** wit
23600 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 h calls to sqlit
23610 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
23620 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f )..**.** ^The po
23630 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
23640 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 are valid until
23650 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
23660 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 n occurs as.** d
23670 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 escribed above,
23680 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 or until [sqlite
23690 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 3_step()] or [sq
236a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
236b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 r.** [sqlite3_fi
236c0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c nalize()] is cal
236d0 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 led. ^The memor
236e0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 y space used to
236f0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 hold strings.**
23700 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 and BLOBs is fre
23710 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
23720 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e . Do <b>not</b>
23730 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 pass the pointe
23740 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b rs returned.** [
23750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
23760 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 lob()], [sqlite3
23770 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c _column_text()],
23780 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 etc. into.** [s
23790 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
237a0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d **.** ^(If a mem
237b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
237c0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
237d0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f ng the evaluatio
237e0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 n of any.** of t
237f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 hese routines, a
23800 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 default value i
23810 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
23820 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a default value.*
23830 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 * is either the
23840 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 integer 0, the f
23850 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
23860 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e mber 0.0, or a N
23870 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 ULL.** pointer.
23880 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c Subsequent call
23890 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
238a0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 rcode()] will re
238b0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
238c0 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e NOMEM].)^.*/.con
238d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
238e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c _column_blob(sql
238f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
23900 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
23910 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
23920 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
23930 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
23940 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
23950 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d es16(sqlite3_stm
23960 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 t*, int iCol);.d
23970 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f ouble sqlite3_co
23980 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 lumn_double(sqli
23990 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
239a0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 Col);.int sqlite
239b0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 3_column_int(sql
239c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
239d0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 iCol);.sqlite3_i
239e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c nt64 sqlite3_col
239f0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 umn_int64(sqlite
23a00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
23a10 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e l);.const unsign
23a20 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 ed char *sqlite3
23a30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c _column_text(sql
23a40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
23a50 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 iCol);.const voi
23a60 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
23a70 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 n_text16(sqlite3
23a80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
23a90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
23aa0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 olumn_type(sqlit
23ab0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
23ac0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c ol);.sqlite3_val
23ad0 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ue *sqlite3_colu
23ae0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 mn_value(sqlite3
23af0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
23b00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
23b10 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 EF: Destroy A Pr
23b20 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
23b30 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 Object.**.** ^T
23b40 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
23b50 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ize() function i
23b60 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 s called to dele
23b70 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
23b80 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 tatement]..** ^I
23b90 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
23ba0 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 was executed suc
23bb0 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 cessfully or not
23bc0 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c executed at all
23bd0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 , then.** SQLITE
23be0 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e _OK is returned.
23bf0 20 5e 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f ^If execution o
23c00 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
23c10 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a failed then an.*
23c20 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f * [error code] o
23c30 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f r [extended erro
23c40 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
23c50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ned..**.** ^This
23c60 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
23c70 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f called at any po
23c80 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 int during the e
23c90 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a xecution of the.
23ca0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
23cb0 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 66 20 74 68 tement]. ^If th
23cc0 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e e virtual machin
23cd0 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d e has not.** com
23ce0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e pleted execution
23cf0 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 when this routi
23d00 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 ne is called, th
23d10 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e at is like.** en
23d20 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 countering an er
23d30 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 ror or an [sqlit
23d40 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 e3_interrupt | i
23d50 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 nterrupt]..** ^I
23d60 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 ncomplete update
23d70 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 s may be rolled
23d80 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 back and transac
23d90 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a tions canceled,.
23da0 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ** depending on
23db0 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 the circumstance
23dc0 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 s, and the.** [e
23dd0 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 rror code] retur
23de0 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c ned will be [SQL
23df0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 ITE_ABORT]..*/.i
23e00 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c nt sqlite3_final
23e10 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ize(sqlite3_stmt
23e20 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
23e30 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
23e40 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
23e50 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a ement Object.**.
23e60 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
23e70 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 eset() function
23e80 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 is called to res
23e90 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 et a [prepared s
23ea0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a tatement].** obj
23eb0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 ect back to its
23ec0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 initial state, r
23ed0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 eady to be re-ex
23ee0 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 ecuted..** ^Any
23ef0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 SQL statement va
23f00 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 riables that had
23f10 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f values bound to
23f20 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 them using.** t
23f30 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
23f40 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
23f50 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 bind_*() API] re
23f60 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 tain their value
23f70 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 s..** Use [sqlit
23f80 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 e3_clear_binding
23f90 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 s()] to reset th
23fa0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a e bindings..**.*
23fb0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
23fc0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 reset(S)] interf
23fd0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b ace resets the [
23fe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
23ff0 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f nt] S.** back to
24000 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
24010 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a f its program..*
24020 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 *.** ^If the mos
24030 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
24040 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
24050 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 )] for the.** [p
24060 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
24070 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 t] S returned [S
24080 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 QLITE_ROW] or [S
24090 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 QLITE_DONE],.**
240a0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 or if [sqlite3_s
240b0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 tep(S)] has neve
240c0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 r before been ca
240d0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 lled on S,.** th
240e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 en [sqlite3_rese
240f0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 t(S)] returns [S
24100 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
24110 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
24120 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cent call to [sq
24130 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 lite3_step(S)] f
24140 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 or the.** [prepa
24150 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
24160 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 indicated an er
24170 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 ror, then.** [sq
24180 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
24190 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f returns an appro
241a0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
241b0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
241c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
241d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 )] interface doe
241e0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
241f0 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e values.** of an
24200 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f y [sqlite3_bind_
24210 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f blob|bindings] o
24220 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
24230 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f statement] S..*/
24240 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 .int sqlite3_res
24250 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 et(sqlite3_stmt
24260 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
24270 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 CAPI3REF: Create
24280 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c Or Redefine SQL
24290 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 Functions.** KE
242a0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f YWORDS: {functio
242b0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
242c0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 nes}.** KEYWORDS
242d0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 : {application-d
242e0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
242f0 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ion}.** KEYWORDS
24300 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 : {application-d
24310 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
24320 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ions}.**.** ^The
24330 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 se two functions
24340 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b (collectively k
24350 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f nown as "functio
24360 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
24370 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 nes").** are use
24380 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e d to add SQL fun
24390 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
243a0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 ates or to redef
243b0 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 ine the behavior
243c0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 .** of existing
243d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
243e0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 aggregates. Th
243f0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
24400 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a e between the.**
24410 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 two is that the
24420 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
24430 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 r, the name of t
24440 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 he (scalar) func
24450 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
24460 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 gate, is encoded
24470 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 in UTF-8 for sq
24480 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
24490 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d ction() and UTF-
244a0 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 16.** for sqlite
244b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
244c0 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 n16()..**.** The
244d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
244e0 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 is the [databas
244f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f e connection] to
24500 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a which the SQL.*
24510 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f * function is to
24520 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 be added. ^If
24530 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d a single program
24540 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 uses more than
24550 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 one database.**
24560 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 connection inter
24570 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 nally, then SQL
24580 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 functions must b
24590 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 e added individu
245a0 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 ally to.** each
245b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
245c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
245d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
245e0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
245f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
24600 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 to be created or
24610 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 .** redefined.
24620 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 ^The length of t
24630 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 he name is limit
24640 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c ed to 255 bytes,
24650 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a exclusive of.**
24660 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
24670 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 ator. Note that
24680 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 the name length
24690 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 limit is in byt
246a0 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 es, not.** chara
246b0 63 74 65 72 73 2e 20 20 5e 41 6e 79 20 61 74 74 cters. ^Any att
246c0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
246d0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
246e0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
246f0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
24700 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 SQLITE_ERROR] be
24710 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a ing returned..**
24720 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 .** ^The third p
24730 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a arameter (nArg).
24740 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ** is the number
24750 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 of arguments th
24760 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 at the SQL funct
24770 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
24780 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 ate takes. ^If t
24790 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 his parameter is
247a0 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 -1, then the SQ
247b0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a L function or.**
247c0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 aggregate may t
247d0 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f ake any number o
247e0 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 f arguments betw
247f0 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 een 0 and the li
24800 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 mit.** set by [s
24810 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 qlite3_limit]([S
24820 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
24830 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 TION_ARG]). If
24840 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 the third.** par
24850 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 ameter is less t
24860 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 han -1 or greate
24870 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 r than 127 then
24880 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a the behavior is.
24890 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a ** undefined..**
248a0 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 .** The fourth p
248b0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 arameter, eTextR
248c0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 ep, specifies wh
248d0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 at.** [SQLITE_UT
248e0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 F8 | text encodi
248f0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e ng] this SQL fun
24900 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f ction prefers fo
24910 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 r.** its paramet
24920 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 ers. Any SQL fu
24930 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
24940 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 ation should be
24950 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 able to work.**
24960 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c work with UTF-8,
24970 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 UTF-16le, or UT
24980 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d F-16be. But som
24990 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
249a0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 s may be.** more
249b0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 efficient with
249c0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 one encoding tha
249d0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 n another. ^An
249e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a application may.
249f0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ** invoke sqlite
24a00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
24a10 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 n() or sqlite3_c
24a20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
24a30 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 () multiple.** t
24a40 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 imes with the sa
24a50 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 me function but
24a60 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 with different v
24a70 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 alues of eTextRe
24a80 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 p..** ^When mult
24a90 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 iple implementat
24aa0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
24ab0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 function are av
24ac0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a ailable, SQLite.
24ad0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 ** will pick the
24ae0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 one that involv
24af0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f es the least amo
24b00 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 unt of data conv
24b10 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 ersion..** If th
24b20 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 ere is only a si
24b30 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ngle implementat
24b40 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e ion which does n
24b50 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 ot care what tex
24b60 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 t.** encoding is
24b70 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 used, then the
24b80 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
24b90 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 should be [SQLIT
24ba0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 E_ANY]..**.** ^(
24bb0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 The fifth parame
24bc0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 ter is an arbitr
24bd0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 ary pointer. Th
24be0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
24bf0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 of the.** funct
24c00 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 ion can gain acc
24c10 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e ess to this poin
24c20 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ter using [sqlit
24c30 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e e3_user_data()].
24c40 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 )^.**.** The sev
24c50 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 enth, eighth and
24c60 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 ninth parameter
24c70 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 s, xFunc, xStep
24c80 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a and xFinal, are.
24c90 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 ** pointers to C
24ca0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 -language functi
24cb0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ons that impleme
24cc0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
24cd0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
24ce0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 ate. ^A scalar S
24cf0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 QL function requ
24d00 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e ires an implemen
24d10 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 tation of the xF
24d20 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 unc.** callback
24d30 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 only; NULL point
24d40 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 ers should be pa
24d50 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 ssed as the xSte
24d60 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 p and xFinal.**
24d70 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 parameters. ^An
24d80 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
24d90 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
24da0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
24db0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e n of xStep.** an
24dc0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c d xFinal and NUL
24dd0 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 L should be pass
24de0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 ed for xFunc. ^T
24df0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 o delete an exis
24e00 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 ting.** SQL func
24e10 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
24e20 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 e, pass NULL for
24e30 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 all three funct
24e40 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a ion callbacks..*
24e50 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d *.** ^It is perm
24e60 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 itted to registe
24e70 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 r multiple imple
24e80 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
24e90 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 e same.** functi
24ea0 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d ons with the sam
24eb0 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 e name but with
24ec0 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 either differing
24ed0 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 numbers of.** a
24ee0 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 rguments or diff
24ef0 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 ering preferred
24f00 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 text encodings.
24f10 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
24f20 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 e.** the impleme
24f30 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 ntation that mos
24f40 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 t closely matche
24f50 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 s the way in whi
24f60 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 ch the.** SQL fu
24f70 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 nction is used.
24f80 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 ^A function imp
24f90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 lementation with
24fa0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a a non-negative.
24fb0 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 ** nArg paramete
24fc0 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 r is a better ma
24fd0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
24fe0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
24ff0 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 on with.** a neg
25000 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 ative nArg. ^A
25010 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
25020 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 he preferred tex
25030 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 t encoding.** ma
25040 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 tches the databa
25050 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 se encoding is a
25060 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 better.** match
25070 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
25080 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
25090 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 ing is different
250a0 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 . .** ^A functi
250b0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 on where the enc
250c0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 oding difference
250d0 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 is between UTF1
250e0 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 6le and UTF16be.
250f0 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d ** is a closer m
25100 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 atch than a func
25110 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 tion where the e
25120 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e ncoding differen
25130 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e ce is.** between
25140 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e UTF8 and UTF16.
25150 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e .**.** ^Built-in
25160 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 functions may b
25170 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 e overloaded by
25180 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d new application-
25190 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
251a0 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 s..** ^The first
251b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
251c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 ined function wi
251d0 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 th a given name
251e0 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a overrides all.**
251f0 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 built-in functi
25200 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 ons in the same
25210 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
25220 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 tion] with the s
25230 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75 ame name..** ^Su
25240 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61 bsequent applica
25250 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
25260 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ctions of the sa
25270 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 me name only ove
25280 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 rride .** prior
25290 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
252a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 ned functions th
252b0 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20 at are an exact
252c0 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a match for the.**
252d0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d number of param
252e0 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72 eters and prefer
252f0 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a red encoding..**
25300 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 .** ^An applicat
25310 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
25320 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 tion is permitte
25330 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a d to call other.
25340 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
25350 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 aces. However,
25360 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 such calls must
25370 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 not.** close the
25380 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
25390 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a tion nor finaliz
253a0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 e or reset the p
253b0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
253c0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 ment in which th
253d0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 e function is ru
253e0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 nning..*/.int sq
253f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
25400 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 ction(. sqlite3
25410 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *db,. const ch
25420 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d ar *zFunctionNam
25430 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
25440 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
25450 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
25460 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
25470 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
25480 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
25490 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
254a0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
254b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
254c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
254d0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
254e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
254f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
25500 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a ate_function16(.
25510 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
25520 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 const void *zFu
25530 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
25540 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
25550 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
25560 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
25570 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
25580 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
25590 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
255a0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
255b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
255c0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
255d0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
255e0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
255f0 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a text*).);../*.**
25600 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 CAPI3REF: Text
25610 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 Encodings.**.**
25620 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 These constant d
25630 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f efine integer co
25640 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 des that represe
25650 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a nt the various.*
25660 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 * text encodings
25670 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
25680 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 Lite..*/.#define
25690 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 SQLITE_UTF8
256a0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
256b0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 SQLITE_UTF16LE
256c0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
256d0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 SQLITE_UTF16BE
256e0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
256f0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 SQLITE_UTF16
25700 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 4 /* U
25710 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f se native byte o
25720 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rder */.#define
25730 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 SQLITE_ANY
25740 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 5 /* sq
25750 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
25760 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 ction only */.#d
25770 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
25780 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 16_ALIGNED 8
25790 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
257a0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c te_collation onl
257b0 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 y */../*.** CAPI
257c0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 3REF: Deprecated
257d0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 Functions.** DE
257e0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 PRECATED.**.** T
257f0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
25800 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e re [deprecated].
25810 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 In order to ma
25820 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 intain.** backwa
25830 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
25840 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 y with older cod
25850 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f e, these functio
25860 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 ns continue .**
25870 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e to be supported.
25880 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 However, new a
25890 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
258a0 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 ld avoid.** the
258b0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e use of these fun
258c0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 ctions. To help
258d0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c encourage peopl
258e0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 e to avoid.** us
258f0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 ing these functi
25900 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 ons, we are not
25910 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f going to tell yo
25920 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a u what they do..
25930 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
25940 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 E_OMIT_DEPRECATE
25950 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 D.SQLITE_DEPRECA
25960 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
25970 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 aggregate_count(
25980 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
25990 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
259a0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
259b0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 _expired(sqlite3
259c0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f _stmt*);.SQLITE_
259d0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
259e0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f qlite3_transfer_
259f0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 bindings(sqlite3
25a00 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f _stmt*, sqlite3_
25a10 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 stmt*);.SQLITE_D
25a20 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
25a30 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 lite3_global_rec
25a40 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 over(void);.SQLI
25a50 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f TE_DEPRECATED vo
25a60 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 id sqlite3_threa
25a70 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b d_cleanup(void);
25a80 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 .SQLITE_DEPRECAT
25a90 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d ED int sqlite3_m
25aa0 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 emory_alarm(void
25ab0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
25ac0 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 3_int64,int),voi
25ad0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 d*,sqlite3_int64
25ae0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a );.#endif../*.**
25af0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 CAPI3REF: Obtai
25b00 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f ning SQL Functio
25b10 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 n Parameter Valu
25b20 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c es.**.** The C-l
25b30 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e anguage implemen
25b40 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 tation of SQL fu
25b50 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
25b60 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 egates uses.** t
25b70 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 his set of inter
25b80 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f face routines to
25b90 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 access the para
25ba0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a meter values on.
25bb0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 ** the function
25bc0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a or aggregate..**
25bd0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 .** The xFunc (f
25be0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 or scalar functi
25bf0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 ons) or xStep (f
25c00 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 or aggregates) p
25c10 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 arameters.** to
25c20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
25c30 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
25c40 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
25c50 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
25c60 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b define callback
25c70 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
25c80 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
25c90 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
25ca0 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 s..** The 4th pa
25cb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 rameter to these
25cc0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e callbacks is an
25cd0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
25ce0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 rs to.** [protec
25cf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
25d00 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 e] objects. The
25d10 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 re is one [sqlit
25d20 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
25d30 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 for.** each par
25d40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 ameter to the SQ
25d50 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 L function. The
25d60 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
25d70 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 used to.** extra
25d80 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 ct values from t
25d90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
25da0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a e] objects..**.*
25db0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
25dc0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 work only with
25dd0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
25de0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
25df0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 s..** Any attemp
25e00 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 t to use these r
25e10 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 outines on an [u
25e20 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
25e30 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a e3_value].** obj
25e40 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 ect results in u
25e50 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f ndefined behavio
25e60 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 r..**.** ^These
25e70 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 routines work ju
25e80 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 st like the corr
25e90 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d esponding [colum
25ea0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
25eb0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 ns].** except th
25ec0 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e at these routin
25ed0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 es take a single
25ee0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
25ef0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
25f00 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 t.** pointer ins
25f10 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 tead of a [sqlit
25f20 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 e3_stmt*] pointe
25f30 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 r and an integer
25f40 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a column number..
25f50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
25f60 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
25f70 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 ) interface extr
25f80 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 acts a UTF-16 st
25f90 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e ring.** in the n
25fa0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 ative byte-order
25fb0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 of the host mac
25fc0 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 hine. ^The.** s
25fd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
25fe0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 t16be() and sqli
25ff0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
26000 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a le() interfaces.
26010 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 ** extract UTF-1
26020 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 6 strings as big
26030 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 -endian and litt
26040 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 le-endian respec
26050 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 tively..**.** ^(
26060 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
26070 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 e_numeric_type()
26080 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
26090 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 pts to apply.**
260a0 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 numeric affinity
260b0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 to the value.
260c0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 This means that
260d0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a an attempt is.**
260e0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 made to convert
260f0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e the value to an
26100 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 integer or floa
26110 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a ting point. If.
26120 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 ** such a conver
26130 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 sion is possible
26140 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 without loss of
26150 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e information (in
26160 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c other.** words,
26170 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 if the value is
26180 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c a string that l
26190 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 ooks like a numb
261a0 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 er).** then the
261b0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 conversion is pe
261c0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 rformed. Otherw
261d0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f ise no conversio
261e0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 n occurs..** The
261f0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
26200 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 | datatype] aft
26210 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 er conversion is
26220 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a returned.)^.**.
26230 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 ** Please pay pa
26240 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 rticular attenti
26250 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 on to the fact t
26260 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 hat the pointer
26270 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d returned.** from
26280 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
26290 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 blob()], [sqlite
262a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
262b0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
262c0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 value_text16()]
262d0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 can be invalidat
262e0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 ed by a subseque
262f0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nt call to.** [s
26300 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
26310 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f es()], [sqlite3_
26320 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d value_bytes16()]
26330 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
26340 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 _text()],.** or
26350 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
26360 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 ext16()]..**.**
26370 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
26380 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
26390 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
263a0 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c ad as.** the SQL
263b0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 function that s
263c0 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c upplied the [sql
263d0 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 ite3_value*] par
263e0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 ameters..*/.cons
263f0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
26400 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 value_blob(sqlit
26410 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
26420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
26430 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 tes(sqlite3_valu
26440 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
26450 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 _value_bytes16(s
26460 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
26470 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 double sqlite3_v
26480 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 alue_double(sqli
26490 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
264a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 sqlite3_value_i
264b0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt(sqlite3_value
264c0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 *);.sqlite3_int6
264d0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 4 sqlite3_value_
264e0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 int64(sqlite3_va
264f0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 lue*);.const uns
26500 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 igned char *sqli
26510 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 te3_value_text(s
26520 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
26530 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
26540 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
26550 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
26560 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
26570 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
26580 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 16le(sqlite3_val
26590 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 ue*);.const void
265a0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
265b0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 text16be(sqlite3
265c0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
265d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 lite3_value_type
265e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
265f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
26600 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
26610 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
26620 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
26630 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 F: Obtain Aggreg
26640 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e ate Function Con
26650 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 text.**.** Imple
26660 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 mentions of aggr
26670 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
26680 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 ons use this.**
26690 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 routine to alloc
266a0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 ate memory for s
266b0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 toring their sta
266c0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 te..**.** ^The f
266d0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 irst time the sq
266e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
266f0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 context(C,N) rou
26700 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a tine is called .
26710 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 ** for a particu
26720 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 lar aggregate fu
26730 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a nction, SQLite.*
26740 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 * allocates N of
26750 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 memory, zeroes
26760 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c out that memory,
26770 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 and returns a p
26780 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
26790 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e new memory. ^On
267a0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
267b0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a equent calls to.
267c0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 ** sqlite3_aggre
267d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 gate_context() f
267e0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 or the same aggr
267f0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
26800 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 nstance,.** the
26810 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 same buffer is r
26820 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 eturned. Sqlite
26830 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
26840 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c ext() is normall
26850 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 y.** called once
26860 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 for each invoca
26870 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 tion of the xSte
26880 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 p callback and t
26890 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 hen one.** last
268a0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 time when the xF
268b0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 inal callback is
268c0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 invoked. ^(Whe
268d0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a n no rows match.
268e0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 ** an aggregate
268f0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 query, the xStep
26900 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 () callback of t
26910 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e he aggregate fun
26920 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ction.** impleme
26930 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 ntation is never
26940 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e called and xFin
26950 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 al() is called e
26960 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 xactly once..**
26970 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 In those cases,
26980 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
26990 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 e_context() migh
269a0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 t be called for
269b0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d the.** first tim
269c0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 e from within xF
269d0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 inal().)^.**.**
269e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 ^The sqlite3_agg
269f0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
26a00 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ,N) routine retu
26a10 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
26a20 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 er if N is.** le
26a30 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c ss than or equal
26a40 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 to zero or if a
26a50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 memory allocate
26a60 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a error occurs..*
26a70 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e *.** ^(The amoun
26a80 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 t of space alloc
26a90 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ated by sqlite3_
26aa0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
26ab0 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 t(C,N) is.** det
26ac0 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e ermined by the N
26ad0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 parameter on fi
26ae0 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 rst successful c
26af0 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 all. Changing t
26b00 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e he.** value of N
26b10 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
26b20 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 all to sqlite3_a
26b30 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
26b40 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 () within.** the
26b50 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 same aggregate
26b60 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 function instanc
26b70 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a e will not resiz
26b80 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 e the memory.**
26b90 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a allocation.)^.**
26ba0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f .** ^SQLite auto
26bb0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 matically frees
26bc0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
26bd0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 ated by .** sqli
26be0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
26bf0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 ntext() when the
26c00 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 aggregate query
26c10 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a concludes..**.*
26c20 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
26c30 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 meter must be a
26c40 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b copy of the.** [
26c50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
26c60 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 | SQL function c
26c70 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 ontext] that is
26c80 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
26c90 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 ter.** to the xS
26ca0 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 tep or xFinal ca
26cb0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 llback routine t
26cc0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
26cd0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 he aggregate.**
26ce0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
26cf0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 This routine mus
26d00 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
26d10 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
26d20 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
26d30 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
26d40 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
26d50 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c ng..*/.void *sql
26d60 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
26d70 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 ontext(sqlite3_c
26d80 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 ontext*, int nBy
26d90 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tes);../*.** CAP
26da0 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 I3REF: User Data
26db0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
26dc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
26dd0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 3_user_data() in
26de0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
26df0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
26e00 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 pointer that wa
26e10 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 s the pUserData
26e20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 parameter (the 5
26e30 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a th parameter).**
26e40 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
26e50 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
26e60 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
26e70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
26e80 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
26e90 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
26ea0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
26eb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
26ec0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
26ed0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
26ee0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
26ef0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
26f00 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
26f10 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 h.** the applica
26f20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
26f30 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
26f40 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
26f50 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c e3_user_data(sql
26f60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
26f70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
26f80 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
26f90 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f tion For Functio
26fa0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ns.**.** ^The sq
26fb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
26fc0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 _handle() interf
26fd0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
26fe0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
26ff0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
27000 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
27010 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d ] (the 1st param
27020 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
27030 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
27040 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
27050 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
27060 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
27070 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
27080 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
27090 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
270a0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
270b0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c function..*/.sql
270c0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f ite3 *sqlite3_co
270d0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
270e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
270f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
27100 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 EF: Function Aux
27110 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a iliary Data.**.*
27120 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
27130 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 two functions ma
27140 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 y be used by sca
27150 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
27160 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
27170 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
27180 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
27190 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
271a0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
271b0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
271c0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
271d0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
271e0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
271f0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
27200 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
27210 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
27220 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
27230 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 be preserved. T
27240 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 his may.** be us
27250 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c ed, for example,
27260 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 to add a regula
27270 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 r-expression mat
27280 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 ching scalar.**
27290 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
272a0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
272b0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
272c0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 pression is stor
272d0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 ed as.** metadat
272e0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
272f0 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 h the SQL value
27300 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 passed as the re
27310 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
27320 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 .** pattern. Th
27330 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c e compiled regul
27340 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 ar expression ca
27350 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d n be reused on m
27360 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 ultiple.** invoc
27370 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
27380 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 me function so t
27390 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c hat the original
273a0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a pattern string.
273b0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ** does not need
273c0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 to be recompile
273d0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 d on each invoca
273e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tion..**.** ^The
273f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
27400 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
27410 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
27420 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 er to the metada
27430 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ta.** associated
27440 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
27450 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 set_auxdata() fu
27460 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 nction with the
27470 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 Nth argument.**
27480 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 value to the app
27490 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
274a0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e function. ^If n
274b0 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 o metadata has b
274c0 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e een ever.** been
274d0 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 set for the Nth
274e0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 argument of the
274f0 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 function, or if
27500 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
27510 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 ng.** function p
27520 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 arameter has cha
27530 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d nged since the m
27540 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 eta-data was set
27550 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 ,.** then sqlite
27560 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_get_auxdata()
27570 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
27580 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
27590 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
275a0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
275b0 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 ce saves the met
275c0 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 adata.** pointed
275d0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 to by its 3rd p
275e0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 arameter as the
275f0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 metadata for the
27600 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e N-th.** argumen
27610 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 t of the applica
27620 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
27630 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 ction. Subseque
27640 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 nt.** calls to s
27650 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
27660 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 ta() might retur
27670 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 n this data, if
27680 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 it has.** not be
27690 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a en destroyed..**
276a0 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e ^If it is not N
276b0 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c ULL, SQLite will
276c0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 invoke the dest
276d0 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 ructor.** functi
276e0 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 on given by the
276f0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
27700 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
27710 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 data() on.** the
27720 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 metadata when t
27730 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
27740 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 function parame
27750 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f ter changes.** o
27760 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 r when the SQL s
27770 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 tatement complet
27780 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f es, whichever co
27790 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a mes first..**.**
277a0 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 SQLite is free
277b0 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 to call the dest
277c0 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 ructor and drop
277d0 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a metadata on any.
277e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 ** parameter of
277f0 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 any function at
27800 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 any time. ^The
27810 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 only guarantee i
27820 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 s that.** the de
27830 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 structor will be
27840 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 called before t
27850 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 he metadata is d
27860 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ropped..**.** ^(
27870 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 In practice, met
27880 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 adata is preserv
27890 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 ed between funct
278a0 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a ion calls for.**
278b0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 expressions tha
278c0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 t are constant a
278d0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 t compile time.
278e0 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 This includes li
278f0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 teral.** values
27900 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d and [parameters]
27910 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 .)^.**.** These
27920 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
27930 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
27940 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
27950 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c which.** the SQL
27960 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
27970 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 ning..*/.void *s
27980 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
27990 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
279a0 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 xt*, int N);.voi
279b0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 d sqlite3_set_au
279c0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f xdata(sqlite3_co
279d0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 ntext*, int N, v
279e0 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 oid*, void (*)(v
279f0 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 oid*));.../*.**
27a00 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 CAPI3REF: Consta
27a10 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 nts Defining Spe
27a20 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 cial Destructor
27a30 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 Behavior.**.** T
27a40 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c hese are special
27a50 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 values for the
27a60 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 destructor that
27a70 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 is passed in as
27a80 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 the.** final arg
27a90 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 ument to routine
27aa0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f s like [sqlite3_
27ab0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 result_blob()].
27ac0 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 ^If the destruc
27ad0 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 tor.** argument
27ae0 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 is SQLITE_STATIC
27af0 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
27b00 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e the content poin
27b10 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a ter is constant.
27b20 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 ** and will neve
27b30 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f r change. It do
27b40 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
27b50 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 e destroyed. ^T
27b60 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 he.** SQLITE_TRA
27b70 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 NSIENT value mea
27b80 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
27b90 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ent will likely
27ba0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 change in.** the
27bb0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 near future and
27bc0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f that SQLite sho
27bd0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e uld make its own
27be0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
27bf0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 .** the content
27c00 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 before returning
27c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 ..**.** The type
27c20 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 def is necessary
27c30 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 to work around
27c40 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 problems in cert
27c50 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 ain.** C++ compi
27c60 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 lers. See ticke
27c70 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 t #2191..*/.type
27c80 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 def void (*sqlit
27c90 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 e3_destructor_ty
27ca0 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 pe)(void*);.#def
27cb0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ine SQLITE_STATI
27cc0 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 C ((sqlite3
27cd0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 _destructor_type
27ce0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 )0).#define SQLI
27cf0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 TE_TRANSIENT (
27d00 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 (sqlite3_destruc
27d10 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a tor_type)-1)../*
27d20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
27d30 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 tting The Result
27d40 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 Of An SQL Funct
27d50 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ion.**.** These
27d60 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
27d70 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f d by the xFunc o
27d80 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 r xFinal callbac
27d90 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 ks that.** imple
27da0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f ment SQL functio
27db0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
27dc0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 s. See.** [sqli
27dd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
27de0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ion()] and [sqli
27df0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
27e00 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 ion16()].** for
27e10 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
27e20 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 mation..**.** Th
27e30 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f ese functions wo
27e40 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b rk very much lik
27e50 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 e the [parameter
27e60 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 binding] family
27e70 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 of.** functions
27e80 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 used to bind va
27e90 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 lues to host par
27ea0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 ameters in prepa
27eb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a red statements..
27ec0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 ** Refer to the
27ed0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
27ee0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
27ef0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 r additional inf
27f00 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
27f10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
27f20 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 ult_blob() inter
27f30 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
27f40 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 sult from.** an
27f50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
27f60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
27f70 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 be the BLOB whos
27f80 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 e content is poi
27f90 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 nted.** to by th
27fa0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
27fb0 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 er and which is
27fc0 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 N bytes long whe
27fd0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 re N is the.** t
27fe0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a hird parameter..
27ff0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
28000 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c e3_result_zerobl
28010 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 ob() interfaces
28020 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f set the result o
28030 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 f.** the applica
28040 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
28050 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c ction to be a BL
28060 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c OB containing al
28070 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 l zero.** bytes
28080 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 and N bytes in s
28090 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 ize, where N is
280a0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
280b0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2nd parameter..
280c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
280d0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 e3_result_double
280e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
280f0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f s the result fro
28100 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 m.** an applicat
28110 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
28120 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f tion to be a flo
28130 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
28140 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 e specified.** b
28150 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 y its 2nd argume
28160 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 nt..**.** ^The s
28170 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
28180 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ror() and sqlite
28190 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
281a0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 () functions.**
281b0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d cause the implem
281c0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 ented SQL functi
281d0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 on to throw an e
281e0 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 xception..** ^SQ
281f0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 Lite uses the st
28200 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 ring pointed to
28210 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 by the.** 2nd pa
28220 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 rameter of sqlit
28230 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
28240 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 ) or sqlite3_res
28250 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a ult_error16().**
28260 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 as the text of
28270 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
28280 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 . ^SQLite inter
28290 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a prets the error.
282a0 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e ** message strin
282b0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 g from sqlite3_r
282c0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 esult_error() as
282d0 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a UTF-8. ^SQLite.
282e0 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 ** interprets th
282f0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 e string from sq
28300 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
28310 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 or16() as UTF-16
28320 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 in native.** by
28330 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 te order. ^If t
28340 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
28350 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
28360 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 sult_error().**
28370 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
28380 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e t_error16() is n
28390 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c egative then SQL
283a0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 ite takes as the
283b0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
283c0 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 e all text up th
283d0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 rough the first
283e0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a zero character..
283f0 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 ** ^If the third
28400 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
28410 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
28420 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 or() or.** sqlit
28430 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
28440 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 6() is non-negat
28450 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 ive then SQLite
28460 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a takes that many.
28470 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 ** bytes (not ch
28480 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 aracters) from t
28490 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
284a0 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 as the error me
284b0 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 ssage..** ^The s
284c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
284d0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ror() and sqlite
284e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
284f0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d ().** routines m
28500 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f ake a private co
28510 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 py of the error
28520 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 message text bef
28530 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 ore.** they retu
28540 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 rn. Hence, the
28550 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e calling function
28560 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 can deallocate
28570 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 or.** modify the
28580 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 text after they
28590 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 return without
285a0 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 harm..** ^The sq
285b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
285c0 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 or_code() functi
285d0 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 on changes the e
285e0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 rror code.** ret
285f0 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 urned by SQLite
28600 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 as a result of a
28610 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e n error in a fun
28620 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 ction. ^By defa
28630 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f ult,.** the erro
28640 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 r code is SQLITE
28650 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 _ERROR. ^A subs
28660 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 equent call to s
28670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
28680 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 ror().** or sqli
28690 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
286a0 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 16() resets the
286b0 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 error code to SQ
286c0 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a LITE_ERROR..**.*
286d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
286e0 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 esult_toobig() i
286f0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
28700 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 SQLite to throw
28710 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 an error.** indi
28720 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 cating that a st
28730 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 ring or BLOB is
28740 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 to long to repre
28750 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 sent..**.** ^The
28760 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28770 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 nomem() interfac
28780 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
28790 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f to throw an erro
287a0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 r.** indicating
287b0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c that a memory al
287c0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e location failed.
287d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
287e0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 te3_result_int()
287f0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
28800 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
28810 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
28820 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
28830 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
28840 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 e 32-bit signed
28850 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
28860 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
28870 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e d argument..** ^
28880 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
28890 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 lt_int64() inter
288a0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
288b0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 turn value.** of
288c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
288d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
288e0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 n to be the 64-b
288f0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
28900 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e r.** value given
28910 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 in the 2nd argu
28920 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ment..**.** ^The
28930 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28940 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 null() interface
28950 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
28960 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
28970 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
28980 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
28990 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
289a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
289b0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 ult_text(), sqli
289c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
289d0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6(),.** sqlite3_
289e0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
289f0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 ), and sqlite3_r
28a00 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 esult_text16be()
28a10 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 interfaces.** s
28a20 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 et the return va
28a30 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 lue of the appli
28a40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
28a50 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a unction to be.**
28a60 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 a text string w
28a70 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e hich is represen
28a80 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 ted as UTF-8, UT
28a90 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
28aa0 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 order,.** UTF-1
28ab0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 6 little endian,
28ac0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 or UTF-16 big e
28ad0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 ndian, respectiv
28ae0 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ely..** ^SQLite
28af0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 takes the text r
28b00 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 esult from the a
28b10 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a pplication from.
28b20 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d ** the 2nd param
28b30 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 eter of the sqli
28b40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
28b50 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
28b60 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 ^If the 3rd para
28b70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
28b80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
28b90 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
28ba0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
28bb0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 n SQLite takes r
28bc0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 esult text from
28bd0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
28be0 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 r.** through the
28bf0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 first zero char
28c00 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 acter..** ^If th
28c10 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
28c20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
28c30 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
28c40 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e rfaces.** is non
28c50 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 -negative, then
28c60 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e as many bytes (n
28c70 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f ot characters) o
28c80 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f f the text.** po
28c90 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 inted to by the
28ca0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 2nd parameter ar
28cb0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 e taken as the a
28cc0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
28cd0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 ed.** function r
28ce0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 esult..** ^If th
28cf0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
28d00 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
28d10 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
28d20 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
28d30 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
28d40 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 is a non-NULL p
28d50 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
28d60 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a ite calls that.*
28d70 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 * function as th
28d80 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 e destructor on
28d90 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
28da0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 result when it
28db0 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 has.** finished
28dc0 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
28dd0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 t..** ^If the 4t
28de0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
28df0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
28e00 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
28e10 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 es or to.** sqli
28e20 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
28e30 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
28e40 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 onstant SQLITE_S
28e50 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 TATIC, then SQLi
28e60 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 te.** assumes th
28e70 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 at the text or B
28e80 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e LOB result is in
28e90 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 constant space
28ea0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 and does not.**
28eb0 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 copy the content
28ec0 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 of the paramete
28ed0 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 r nor call a des
28ee0 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 tructor on the c
28ef0 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 ontent.** when i
28f00 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 t has finished u
28f10 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 sing that result
28f20 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 ..** ^If the 4th
28f30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
28f40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
28f50 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
28f60 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f s.** or sqlite3_
28f70 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
28f80 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
28f90 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ant SQLITE_TRANS
28fa0 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c IENT.** then SQL
28fb0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
28fc0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 of the result i
28fd0 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e nto space obtain
28fe0 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 ed from.** from
28ff0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
29000 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 )] before it ret
29010 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 urns..**.** ^The
29020 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
29030 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
29040 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
29050 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c t of.** the appl
29060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
29070 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
29080 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e copy the.** [un
29090 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
290a0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
290b0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
290c0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 2nd parameter.
290d0 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
290e0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
290f0 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
29100 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
29110 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
29120 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
29130 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
29140 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
29150 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
29160 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
29170 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
29180 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
29190 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
291a0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 hout harm..** ^A
291b0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
291c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
291d0 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 t may always be
291e0 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a used where an.**
291f0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
29200 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
29210 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c ect is required,
29220 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 so either.** ki
29230 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 nd of [sqlite3_v
29240 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e alue] object can
29250 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 be used with th
29260 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
29270 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 .** If these rou
29280 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
29290 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
292a0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
292b0 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e d.** than the on
292c0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
292d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
292e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 ined function th
292f0 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 at received.** t
29300 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
29310 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 ext] pointer, th
29320 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
29330 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 defined..*/.void
29340 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
29350 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e blob(sqlite3_con
29360 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
29370 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
29380 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
29390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
293a0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e uble(sqlite3_con
293b0 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a text*, double);.
293c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
293d0 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 ult_error(sqlite
293e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
293f0 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 t char*, int);.v
29400 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
29410 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 lt_error16(sqlit
29420 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
29430 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a st void*, int);.
29440 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
29450 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 ult_error_toobig
29460 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29470 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
29480 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f _result_error_no
29490 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 mem(sqlite3_cont
294a0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 ext*);.void sqli
294b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
294c0 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f _code(sqlite3_co
294d0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f ntext*, int);.vo
294e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
294f0 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f t_int(sqlite3_co
29500 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f ntext*, int);.vo
29510 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
29520 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f t_int64(sqlite3_
29530 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
29540 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 3_int64);.void s
29550 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 qlite3_result_nu
29560 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ll(sqlite3_conte
29570 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 xt*);.void sqlit
29580 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 e3_result_text(s
29590 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
295a0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e const char*, in
295b0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
295c0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
295d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 _result_text16(s
295e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
295f0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
29600 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
29610 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
29620 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
29630 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29640 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
29650 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
29660 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
29670 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
29680 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
29690 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
296a0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 int,void(*)(voi
296b0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 d*));.void sqlit
296c0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
296d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
296e0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a , sqlite3_value*
296f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
29700 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
29710 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
29720 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a , int n);../*.**
29730 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e CAPI3REF: Defin
29740 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 e New Collating
29750 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 Sequences.**.**
29760 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
29770 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 are used to add
29780 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 new collation se
29790 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a quences to the.*
297a0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
297b0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 ection] specifie
297c0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
297d0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
297e0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 The name of the
297f0 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 new collation se
29800 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 quence is specif
29810 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 ied as a UTF-8 s
29820 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c tring.** for sql
29830 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
29840 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 ation() and sqli
29850 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
29860 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 tion_v2().** and
29870 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 a UTF-16 string
29880 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
29890 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
298a0 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73 ). ^In all cases
298b0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 .** the name is
298c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
298d0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 cond function ar
298e0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gument..**.** ^T
298f0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
29900 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 t may be one of
29910 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 the constants [S
29920 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 QLITE_UTF8],.**
29930 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
29940 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 , or [SQLITE_UTF
29950 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 16BE], indicatin
29960 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d g that the user-
29970 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 supplied.** rout
29980 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 ine expects to b
29990 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 e passed pointer
299a0 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 s to strings enc
299b0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 oded using UTF-8
299c0 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 ,.** UTF-16 litt
299d0 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 le-endian, or UT
299e0 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c F-16 big-endian,
299f0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e respectively. ^
29a00 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 The.** third arg
29a10 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f ument might also
29a20 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 be [SQLITE_UTF1
29a30 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 6] to indicate t
29a40 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a hat the routine.
29a50 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 ** expects point
29a60 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36 ers to be UTF-16
29a70 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 strings in the
29a80 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
29a90 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67 r, or the.** arg
29aa0 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51 ument can be [SQ
29ab0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e LITE_UTF16_ALIGN
29ac0 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 ED] if the.** th
29ad0 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 e routine expect
29ae0 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 s pointers to 16
29af0 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 -bit word aligne
29b00 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 d strings.** of
29b10 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
29b20 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
29b30 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 .**.** A pointer
29b40 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 to the user sup
29b50 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 plied routine mu
29b60 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 st be passed as
29b70 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 the fifth.** arg
29b80 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69 ument. ^If it i
29b90 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 s NULL, this is
29ba0 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 the same as dele
29bb0 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 ting the collati
29bc0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 on.** sequence (
29bd0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 so that SQLite c
29be0 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e annot call it an
29bf0 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 ymore)..** ^Each
29c00 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 time the applic
29c10 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 ation supplied f
29c20 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b unction is invok
29c30 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 ed, it is passed
29c40 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 .** as its first
29c50 20 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 parameter a cop
29c60 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 y of the void* p
29c70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 assed as the fou
29c80 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 rth argument.**
29c90 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 to sqlite3_creat
29ca0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 e_collation() or
29cb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
29cc0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a collation16()..*
29cd0 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e *.** ^The remain
29ce0 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ing arguments to
29cf0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
29d00 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e -supplied routin
29d10 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 e are two string
29d20 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 s,.** each repre
29d30 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e sented by a (len
29d40 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 gth, data) pair
29d50 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 and encoded in t
29d60 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 he encoding.** t
29d70 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61 hat was passed a
29d80 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 s the third argu
29d90 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f ment when the co
29da0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
29db0 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 was.** register
29dc0 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 ed. {END} The a
29dd0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
29de0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 ed collation rou
29df0 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 tine should.** r
29e00 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 eturn negative,
29e10 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 zero or positive
29e20 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 if the first st
29e30 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 ring is less tha
29e40 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 n,.** equal to,
29e50 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 or greater than
29e60 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e the second strin
29e70 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 g. i.e. (STRING1
29e80 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a - STRING2)..**.
29e90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
29ea0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
29eb0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 _v2() works like
29ec0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
29ed0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 collation().** e
29ee0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61 xcept that it ta
29ef0 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 kes an extra arg
29f00 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
29f10 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a destructor for.
29f20 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e ** the collation
29f30 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 . ^The destruct
29f40 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 or is called whe
29f50 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 n the collation
29f60 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 is.** destroyed
29f70 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 and is passed a
29f80 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 copy of the four
29f90 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 th parameter voi
29fa0 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 d* pointer.** of
29fb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 the sqlite3_cre
29fc0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
29fd0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f ()..** ^Collatio
29fe0 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 ns are destroyed
29ff0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f when they are o
2a000 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 verridden by lat
2a010 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a er calls to the.
2a020 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 ** collation cre
2a030 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 ation functions
2a040 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 or when the [dat
2a050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2a060 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 ] is closed.** u
2a070 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c sing [sqlite3_cl
2a080 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 ose()]..**.** Se
2a090 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 e also: [sqlite
2a0a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
2a0b0 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ed()] and [sqlit
2a0c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
2a0d0 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 ded16()]..*/.int
2a0e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2a0f0 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c collation(. sql
2a100 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 ite3*, . const
2a110 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 char *zName, .
2a120 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 int eTextRep, .
2a130 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 void*,. int(*x
2a140 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 Compare)(void*,i
2a150 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 nt,const void*,i
2a160 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a nt,const void*).
2a170 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
2a180 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
2a190 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 v2(. sqlite3*,
2a1a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2a1b0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 Name, . int eTe
2a1c0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c xtRep, . void*,
2a1d0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
2a1e0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
2a1f0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
2a200 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 t void*),. void
2a210 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
2a220 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
2a230 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2a240 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a on16(. sqlite3*
2a250 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 , . const void
2a260 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 *zName,. int eT
2a270 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a extRep, . void*
2a280 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
2a290 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
2a2a0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
2a2b0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
2a2c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
2a2d0 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 llation Needed C
2a2e0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 allbacks {H16700
2a2f0 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S20300>.**.**
2a300 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e ^To avoid havin
2a310 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c g to register al
2a320 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 l collation sequ
2a330 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 ences before a d
2a340 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 atabase.** can b
2a350 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 e used, a single
2a360 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
2a370 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 on may be regist
2a380 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a ered with the.**
2a390 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2a3a0 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c ction] to be cal
2a3b0 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 led whenever an
2a3c0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 undefined collat
2a3d0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 ion.** sequence
2a3e0 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a is required..**.
2a3f0 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 ** ^If the funct
2a400 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 ion is registere
2a410 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 d using the sqli
2a420 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
2a430 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 eded() API,.** t
2a440 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 hen it is passed
2a450 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e the names of un
2a460 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f defined collatio
2a470 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 n sequences as s
2a480 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 trings.** encode
2a490 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 d in UTF-8. ^If
2a4a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
2a4b0 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 n_needed16() is
2a4c0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d used,.** the nam
2a4d0 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 es are passed as
2a4e0 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 UTF-16 in machi
2a4f0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f ne native byte o
2a500 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c rder..** ^A call
2a510 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 to either funct
2a520 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 ion replaces any
2a530 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 existing callba
2a540 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e ck..**.** ^(When
2a550 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
2a560 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 invoked, the fi
2a570 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 rst argument pas
2a580 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a sed is a copy.**
2a590 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 of the second a
2a5a0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
2a5b0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
2a5c0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 ded() or.** sqli
2a5d0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
2a5e0 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 eded16(). The s
2a5f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
2a600 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a s the database.*
2a610 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 * connection. T
2a620 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
2a630 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c t is one of [SQL
2a640 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 ITE_UTF8], [SQLI
2a650 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 TE_UTF16BE],.**
2a660 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 or [SQLITE_UTF16
2a670 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 LE], indicating
2a680 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 the most desirab
2a690 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 le form of the c
2a6a0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 ollation.** sequ
2a6b0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 ence function re
2a6c0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 quired. The fou
2a6d0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
2a6e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
2a6f0 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c .** required col
2a700 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e lation sequence.
2a710 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c )^.**.** The cal
2a720 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 lback function s
2a730 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 hould register t
2a740 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 he desired colla
2a750 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tion using.** [s
2a760 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2a770 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c llation()], [sql
2a780 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
2a790 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a ation16()], or.*
2a7a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
2a7b0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
2a7c0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
2a7d0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
2a7e0 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ed(. sqlite3*,
2a7f0 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 . void*, . voi
2a800 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 d(*)(void*,sqlit
2a810 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 e3*,int eTextRep
2a820 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b ,const char*).);
2a830 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2a840 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
2a850 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
2a860 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 void*,. void(*)
2a870 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c (void*,sqlite3*,
2a880 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e int eTextRep,con
2a890 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
2a8a0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 .** Specify the
2a8b0 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 key for an encry
2a8c0 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 pted database.
2a8d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f This routine sho
2a8e0 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 uld be.** called
2a8f0 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c right after sql
2a900 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a ite3_open()..**.
2a910 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 ** The code to i
2a920 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 mplement this AP
2a930 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 I is not availab
2a940 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 le in the public
2a950 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 release.** of S
2a960 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 QLite..*/.int sq
2a970 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c lite3_key(. sql
2a980 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
2a990 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
2a9a0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
2a9b0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 keyed */. const
2a9c0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 void *pKey, int
2a9d0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 nKey /* The
2a9e0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a key */.);../*.*
2a9f0 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 * Change the key
2aa00 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 on an open data
2aa10 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 base. If the cu
2aa20 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 rrent database i
2aa30 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 s not.** encrypt
2aa40 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ed, this routine
2aa50 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 will encrypt it
2aa60 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 . If pNew==0 or
2aa70 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a nNew==0, the.**
2aa80 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 database is dec
2aa90 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 rypted..**.** Th
2aaa0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d e code to implem
2aab0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 ent this API is
2aac0 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e not available in
2aad0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 the public rele
2aae0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ase.** of SQLite
2aaf0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2ab00 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 _rekey(. sqlite
2ab10 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2ab20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
2ab30 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
2ab40 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
2ab50 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
2ab60 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 ey /* The ne
2ab70 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a w key */.);../*.
2ab80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 ** CAPI3REF: Sus
2ab90 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 pend Execution F
2aba0 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a or A Short Time.
2abb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2abc0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 e3_sleep() funct
2abd0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 ion causes the c
2abe0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f urrent thread to
2abf0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 suspend executi
2ac00 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 on.** for at lea
2ac10 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d st a number of m
2ac20 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 illiseconds spec
2ac30 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 ified in its par
2ac40 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ameter..**.** ^I
2ac50 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 f the operating
2ac60 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 system does not
2ac70 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 support sleep re
2ac80 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d quests with.** m
2ac90 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 illisecond time
2aca0 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e resolution, then
2acb0 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 the time will b
2acc0 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a e rounded up to.
2acd0 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 ** the nearest s
2ace0 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d 62 econd. ^The numb
2acf0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
2ad00 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 ds of sleep actu
2ad10 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 ally.** requeste
2ad20 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 d from the opera
2ad30 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 ting system is r
2ad40 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
2ad50 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 SQLite implement
2ad60 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 s this interface
2ad70 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 by calling the
2ad80 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 xSleep().** meth
2ad90 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c od of the defaul
2ada0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
2adb0 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 object..*/.int s
2adc0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 qlite3_sleep(int
2add0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2ade0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 EF: Name Of The
2adf0 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 Folder Holding T
2ae00 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a emporary Files.*
2ae10 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 67 6c *.** ^If this gl
2ae20 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 obal variable is
2ae30 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
2ae40 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 o a string which
2ae50 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 is.** the name
2ae60 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b of a folder (a.k
2ae70 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 .a. directory),
2ae80 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 then all tempora
2ae90 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 ry files.** crea
2aea0 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 ted by SQLite wh
2aeb0 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 en using a built
2aec0 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 -in [sqlite3_vfs
2aed0 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 | VFS].** will
2aee0 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 be placed in tha
2aef0 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 5e 49 t directory. ^I
2af00 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a f this variable.
2af10 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 ** is a NULL poi
2af20 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 nter, then SQLit
2af30 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 e performs a sea
2af40 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f rch for an appro
2af50 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 priate.** tempor
2af60 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f ary file directo
2af70 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 ry..**.** It is
2af80 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 not safe to read
2af90 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 or modify this
2afa0 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 variable in more
2afb0 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 than one.** thr
2afc0 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 ead at a time.
2afd0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 It is not safe t
2afe0 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 o read or modify
2aff0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a this variable.*
2b000 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 * if a [database
2b010 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
2b020 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 being used at th
2b030 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 e same time in a
2b040 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 separate.** thr
2b050 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e ead..** It is in
2b060 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 tended that this
2b070 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 variable be set
2b080 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 once.** as part
2b090 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 of process init
2b0a0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 ialization and b
2b0b0 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 efore any SQLite
2b0c0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f interface.** ro
2b0d0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e utines have been
2b0e0 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 called and that
2b0f0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 this variable r
2b100 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a emain unchanged.
2b110 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a ** thereafter..*
2b120 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f *.** ^The [temp_
2b130 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
2b140 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 pragma] may modi
2b150 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 fy this variable
2b160 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 and cause.** it
2b170 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d to point to mem
2b180 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
2b190 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
2b1a0 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 c]. ^Furthermor
2b1b0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f e,.** the [temp_
2b1c0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
2b1d0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 pragma] always a
2b1e0 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 ssumes that any
2b1f0 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 string.** that t
2b200 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 his variable poi
2b210 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 nts to is held i
2b220 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 n memory obtaine
2b230 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 d from .** [sqli
2b240 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 te3_malloc] and
2b250 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 the pragma may a
2b260 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 ttempt to free t
2b270 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 hat memory.** us
2b280 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
2b290 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 e]..** Hence, if
2b2a0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 this variable i
2b2b0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 s modified direc
2b2c0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 tly, either it s
2b2d0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 hould be.** made
2b2e0 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f NULL or made to
2b2f0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 point to memory
2b300 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
2b310 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a sqlite3_malloc].
2b320 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 ** or else the u
2b330 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f se of the [temp_
2b340 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
2b350 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 pragma] should b
2b360 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 e avoided..*/.SQ
2b370 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 LITE_EXTERN char
2b380 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 *sqlite3_temp_d
2b390 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a irectory;../*.**
2b3a0 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 CAPI3REF: Test
2b3b0 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 For Auto-Commit
2b3c0 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 Mode.** KEYWORDS
2b3d0 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f : {autocommit mo
2b3e0 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 de}.**.** ^The s
2b3f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 qlite3_get_autoc
2b400 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 ommit() interfac
2b410 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 e returns non-ze
2b420 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 ro or.** zero if
2b430 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 the given datab
2b440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
2b450 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 s or is not in a
2b460 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a utocommit mode,.
2b470 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e ** respectively.
2b480 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f ^Autocommit mo
2b490 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 de is on by defa
2b4a0 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d ult..** ^Autocom
2b4b0 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 mit mode is disa
2b4c0 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e bled by a [BEGIN
2b4d0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 ] statement..**
2b4e0 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 ^Autocommit mode
2b4f0 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 is re-enabled b
2b500 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 y a [COMMIT] or
2b510 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a [ROLLBACK]..**.*
2b520 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e * If certain kin
2b530 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 ds of errors occ
2b540 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e ur on a statemen
2b550 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 t within a multi
2b560 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 -statement.** tr
2b570 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 ansaction (error
2b580 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c s including [SQL
2b590 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 ITE_FULL], [SQLI
2b5a0 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 TE_IOERR],.** [S
2b5b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 QLITE_NOMEM], [S
2b5c0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 QLITE_BUSY], and
2b5d0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
2b5e0 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a PT]) then the.**
2b5f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 transaction mig
2b600 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 ht be rolled bac
2b610 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e k automatically.
2b620 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 The only way t
2b630 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 o.** find out wh
2b640 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 ether SQLite aut
2b650 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
2b660 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 d back the trans
2b670 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 action after.**
2b680 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 an error is to u
2b690 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e se this function
2b6a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 ..**.** If anoth
2b6b0 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 er thread change
2b6c0 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 s the autocommit
2b6d0 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 status of the d
2b6e0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
2b6f0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 ction while this
2b700 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e routine is runn
2b710 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
2b720 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 turn value.** is
2b730 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 undefined..*/.i
2b740 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 nt sqlite3_get_a
2b750 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 utocommit(sqlite
2b760 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
2b770 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 3REF: Find The D
2b780 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f atabase Handle O
2b790 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 f A Prepared Sta
2b7a0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 tement.**.** ^Th
2b7b0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e e sqlite3_db_han
2b7c0 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 dle interface re
2b7d0 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 turns the [datab
2b7e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2b7f0 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 handle.** to whi
2b800 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 ch a [prepared s
2b810 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 tatement] belong
2b820 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 s. ^The [databa
2b830 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a se connection].*
2b840 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 * returned by sq
2b850 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 lite3_db_handle
2b860 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 is the same [dat
2b870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2b880 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 ].** that was th
2b890 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
2b8a0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 .** to the [sqli
2b8b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2b8c0 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 ] call (or its v
2b8d0 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 ariants) that wa
2b8e0 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 s used to.** cre
2b8f0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e ate the statemen
2b900 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 t in the first p
2b910 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 lace..*/.sqlite3
2b920 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e *sqlite3_db_han
2b930 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 dle(sqlite3_stmt
2b940 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2b950 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 REF: Find the ne
2b960 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 xt prepared stat
2b970 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 ement.**.** ^Thi
2b980 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 s interface retu
2b990 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
2b9a0 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 the next [prepa
2b9b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
2b9c0 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 fter.** pStmt as
2b9d0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
2b9e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2b9f0 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 ection] pDb. ^I
2ba00 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a f pStmt is NULL.
2ba10 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 ** then this int
2ba20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2ba30 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2ba40 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 first prepared s
2ba50 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f tatement.** asso
2ba60 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
2ba70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2ba80 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f ion pDb. ^If no
2ba90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2baa0 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 ent.** satisfies
2bab0 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 the conditions
2bac0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c of this routine,
2bad0 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c it returns NULL
2bae0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 ..**.** The [dat
2baf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2bb00 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 ] pointer D in a
2bb10 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
2bb20 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 ite3_next_stmt(D
2bb30 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 ,S)] must refer
2bb40 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 to an open datab
2bb50 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
2bb60 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 n and in particu
2bb70 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 lar must not be
2bb80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
2bb90 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 */.sqlite3_stmt
2bba0 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 *sqlite3_next_st
2bbb0 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c mt(sqlite3 *pDb,
2bbc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 sqlite3_stmt *p
2bbd0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
2bbe0 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 PI3REF: Commit A
2bbf0 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 nd Rollback Noti
2bc00 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 fication Callbac
2bc10 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 ks {H12950} <S60
2bc20 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 400>.**.** ^The
2bc30 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
2bc40 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 ook() interface
2bc50 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
2bc60 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
2bc70 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
2bc80 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 henever a transa
2bc90 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 ction is [COMMIT
2bca0 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a | committed]..*
2bcb0 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 * ^Any callback
2bcc0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 set by a previou
2bcd0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 s call to sqlite
2bce0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 3_commit_hook().
2bcf0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
2bd00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2bd10 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 ion is overridde
2bd20 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 n..** ^The sqlit
2bd30 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
2bd40 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 () interface reg
2bd50 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
2bd60 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f k.** function to
2bd70 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
2bd80 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 ever a transacti
2bd90 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 on is [ROLLBACK
2bda0 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a | rolled back]..
2bdb0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b ** ^Any callback
2bdc0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f set by a previo
2bdd0 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 us call to sqlit
2bde0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
2bdf0 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 ().** for the sa
2be00 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
2be10 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 ection is overri
2be20 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 dden..** ^The pA
2be30 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 rg argument is p
2be40 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f assed through to
2be50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a the callback..*
2be60 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 * ^If the callba
2be70 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 ck on a commit h
2be80 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 ook function ret
2be90 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a urns non-zero,.*
2bea0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 * then the commi
2beb0 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 t is converted i
2bec0 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a nto a rollback..
2bed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2bee0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 e3_commit_hook(D
2bef0 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 ,C,P) and sqlite
2bf00 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
2bf10 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 D,C,P) functions
2bf20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 .** return the P
2bf30 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 argument from t
2bf40 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c he previous call
2bf50 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e of the same fun
2bf60 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 ction.** on the
2bf70 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
2bf80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 onnection] D, or
2bf90 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 NULL for.** the
2bfa0 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 first call for
2bfb0 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e each function on
2bfc0 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 D..**.** The ca
2bfd0 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 llback implement
2bfe0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 ation must not d
2bff0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
2c000 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
2c010 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2c020 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
2c030 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ked the callback
2c040 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a . Any actions.*
2c050 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 * to modify the
2c060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2c070 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 ion must be defe
2c080 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 rred until after
2c090 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 the.** completi
2c0a0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 on of the [sqlit
2c0b0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 e3_step()] call
2c0c0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 that triggered t
2c0d0 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 he commit.** or
2c0e0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e rollback hook in
2c0f0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 the first place
2c100 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b ..** Note that [
2c110 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2c120 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
2c130 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 e3_step()] both
2c140 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 modify their.**
2c150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2c160 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 ions for the mea
2c170 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 ning of "modify"
2c180 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
2c190 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 ph..**.** ^Regis
2c1a0 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 tering a NULL fu
2c1b0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 nction disables
2c1c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a the callback..**
2c1d0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f .** ^When the co
2c1e0 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 mmit hook callba
2c1f0 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ck routine retur
2c200 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f ns zero, the [CO
2c210 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 MMIT].** operati
2c220 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f on is allowed to
2c230 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c continue normal
2c240 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d ly. ^If the com
2c250 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 mit hook.** retu
2c260 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
2c270 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 en the [COMMIT]
2c280 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 is converted int
2c290 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a o a [ROLLBACK]..
2c2a0 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b ** ^The rollback
2c2b0 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 hook is invoked
2c2c0 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 on a rollback t
2c2d0 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d hat results from
2c2e0 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f a commit.** hoo
2c2f0 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d k returning non-
2c300 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 zero, just as it
2c310 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 would be with a
2c320 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 ny other rollbac
2c330 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 k..**.** ^For th
2c340 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 e purposes of th
2c350 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 is API, a transa
2c360 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f ction is said to
2c370 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f have been.** ro
2c380 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 lled back if an
2c390 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 explicit "ROLLBA
2c3a0 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 CK" statement is
2c3b0 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a executed, or.**
2c3c0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e an error or con
2c3d0 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 straint causes a
2c3e0 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 n implicit rollb
2c3f0 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a ack to occur..**
2c400 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 ^The rollback c
2c410 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 allback is not i
2c420 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e nvoked if a tran
2c430 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 saction is.** au
2c440 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
2c450 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 ed back because
2c460 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2c470 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
2c480 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 d..** ^The rollb
2c490 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ack callback is
2c4a0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 not invoked if a
2c4b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a transaction is.
2c4c0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 ** rolled back b
2c4d0 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 ecause a commit
2c4e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 callback returne
2c4f0 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a d non-zero..**.*
2c500 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b * See also the [
2c510 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
2c520 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ook()] interface
2c530 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
2c540 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 e3_commit_hook(s
2c550 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 qlite3*, int(*)(
2c560 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
2c570 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f void *sqlite3_ro
2c580 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 llback_hook(sqli
2c590 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f te3*, void(*)(vo
2c5a0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a id *), void*);..
2c5b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2c5c0 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 Data Change Noti
2c5d0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 fication Callbac
2c5e0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ks.**.** ^The sq
2c5f0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
2c600 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 k() interface re
2c610 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
2c620 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 ck function.** w
2c630 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
2c640 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 e connection] id
2c650 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
2c660 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a first argument.*
2c670 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 * to be invoked
2c680 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 whenever a row i
2c690 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 s updated, inser
2c6a0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a ted or deleted..
2c6b0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b ** ^Any callback
2c6c0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f set by a previo
2c6d0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 us call to this
2c6e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 function.** for
2c6f0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
2c700 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
2c710 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a overridden..**.*
2c720 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 * ^The second ar
2c730 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
2c740 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 ter to the funct
2c750 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 ion to invoke wh
2c760 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 en a.** row is u
2c770 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 pdated, inserted
2c780 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 or deleted..**
2c790 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
2c7a0 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ent to the callb
2c7b0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
2c7c0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
2c7d0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
2c7e0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 3_update_hook().
2c7f0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
2c800 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e callback argumen
2c810 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c t is one of [SQL
2c820 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 ITE_INSERT], [SQ
2c830 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a LITE_DELETE],.**
2c840 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 or [SQLITE_UPDA
2c850 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f TE], depending o
2c860 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 n the operation
2c870 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 that caused the
2c880 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 callback.** to b
2c890 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 e invoked..** ^T
2c8a0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 he third and fou
2c8b0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f rth arguments to
2c8c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f the callback co
2c8d0 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 ntain pointers t
2c8e0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 o the.** databas
2c8f0 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 e and table name
2c900 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
2c910 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a affected row..**
2c920 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c ^The final call
2c930 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 back parameter i
2c940 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 s the [rowid] of
2c950 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e the row..** ^In
2c960 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 the case of an
2c970 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 update, this is
2c980 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 the [rowid] afte
2c990 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b r the update tak
2c9a0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 es place..**.**
2c9b0 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f ^(The update hoo
2c9c0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 k is not invoked
2c9d0 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 when internal s
2c9e0 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 ystem tables are
2c9f0 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e .** modified (i.
2ca00 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 e. sqlite_master
2ca10 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 and sqlite_sequ
2ca20 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e ence).)^.**.** ^
2ca30 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 In the current i
2ca40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 mplementation, t
2ca50 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a he update hook.*
2ca60 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 * is not invoked
2ca70 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f when duplicatio
2ca80 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 n rows are delet
2ca90 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e ed because of an
2caa0 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 .** [ON CONFLICT
2cab0 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 | ON CONFLICT R
2cac0 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 EPLACE] clause.
2cad0 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 ^Nor is the upd
2cae0 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f ate hook.** invo
2caf0 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 ked when rows ar
2cb00 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 e deleted using
2cb10 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 the [truncate op
2cb20 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 timization]..**
2cb30 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 The exceptions d
2cb40 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 efined in this p
2cb50 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 aragraph might c
2cb60 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 hange in a futur
2cb70 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 e.** release of
2cb80 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 SQLite..**.** Th
2cb90 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d e update hook im
2cba0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 plementation mus
2cbb0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
2cbc0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
2cbd0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
2cbe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
2cbf0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 at invoked the u
2cc00 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 pdate hook. Any
2cc10 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d actions.** to m
2cc20 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 odify the databa
2cc30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 se connection mu
2cc40 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 st be deferred u
2cc50 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a ntil after the.*
2cc60 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 * completion of
2cc70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
2cc80 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 p()] call that t
2cc90 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 riggered the upd
2cca0 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 ate hook..** Not
2ccb0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
2ccc0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
2ccd0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
2cce0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
2ccf0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
2cd00 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
2cd10 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
2cd20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
2cd30 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
2cd40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 * ^The sqlite3_u
2cd50 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 pdate_hook(D,C,P
2cd60 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 ) function.** re
2cd70 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 turns the P argu
2cd80 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 ment from the pr
2cd90 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f evious call.** o
2cda0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 n the same [data
2cdb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2cdc0 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a D, or NULL for.
2cdd0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c ** the first cal
2cde0 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 l on D..**.** Se
2cdf0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
2ce00 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
2ce10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2ce20 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d rollback_hook()]
2ce30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a .** interfaces..
2ce40 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
2ce50 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 _update_hook(.
2ce60 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 sqlite3*, . voi
2ce70 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 d(*)(void *,int
2ce80 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 ,char const *,ch
2ce90 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 ar const *,sqlit
2cea0 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 e3_int64),. voi
2ceb0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 d*.);../*.** CAP
2cec0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 I3REF: Enable Or
2ced0 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 Disable Shared
2cee0 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b Pager Cache.** K
2cef0 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 EYWORDS: {shared
2cf00 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 cache}.**.** ^(
2cf10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 This routine ena
2cf20 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
2cf30 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 the sharing of
2cf40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 the database cac
2cf50 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 he.** and schema
2cf60 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 data structures
2cf70 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 between [databa
2cf80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 se connection |
2cf90 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 connections].**
2cfa0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 to the same data
2cfb0 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 base. Sharing is
2cfc0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 enabled if the
2cfd0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 argument is true
2cfe0 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 .** and disabled
2cff0 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 if the argument
2d000 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a is false.)^.**.
2d010 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e ** ^Cache sharin
2d020 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 g is enabled and
2d030 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e disabled for an
2d040 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e entire process.
2d050 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 .** This is a ch
2d060 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 ange as of SQLit
2d070 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e e version 3.5.0.
2d080 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f In prior versio
2d090 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a ns of SQLite,.**
2d0a0 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 sharing was ena
2d0b0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
2d0c0 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 for each thread
2d0d0 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a separately..**.
2d0e0 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 ** ^(The cache s
2d0f0 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 haring mode set
2d100 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 by this interfac
2d110 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 e effects all su
2d120 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c bsequent.** call
2d130 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 s to [sqlite3_op
2d140 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
2d150 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 open_v2()], and
2d160 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
2d170 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 )]..** Existing
2d180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2d190 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 ions continue us
2d1a0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f e the sharing mo
2d1b0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 de.** that was i
2d1c0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 n effect at the
2d1d0 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f time they were o
2d1e0 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e pened.)^.**.** ^
2d1f0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 (This routine re
2d200 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
2d210 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 ] if shared cach
2d220 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 e was enabled or
2d230 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 disabled.** suc
2d240 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b cessfully. An [
2d250 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
2d260 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 eturned otherwis
2d270 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 e.)^.**.** ^Shar
2d280 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 ed cache is disa
2d290 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
2d2a0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 But this might
2d2b0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 change in.** fut
2d2c0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
2d2d0 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 SQLite. Applica
2d2e0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 tions that care
2d2f0 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 about shared.**
2d300 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 cache setting sh
2d310 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c ould set it expl
2d320 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 icitly..**.** Se
2d330 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 e Also: [SQLite
2d340 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f Shared-Cache Mo
2d350 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 de].*/.int sqlit
2d360 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
2d370 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a _cache(int);../*
2d380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 .** CAPI3REF: At
2d390 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 tempt To Free He
2d3a0 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 ap Memory.**.**
2d3b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c ^The sqlite3_rel
2d3c0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e ease_memory() in
2d3d0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
2d3e0 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 to free N bytes
2d3f0 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f .** of heap memo
2d400 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 ry by deallocati
2d410 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c ng non-essential
2d420 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
2d430 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 ons.** held by t
2d440 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 he database libr
2d450 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 ary. Memory us
2d460 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 ed to cache data
2d470 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f base.** pages to
2d480 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d improve perform
2d490 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 ance is an examp
2d4a0 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 le of non-essent
2d4b0 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e ial memory..** ^
2d4c0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
2d4d0 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 memory() returns
2d4e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2d4f0 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 ytes actually fr
2d500 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 eed,.** which mi
2d510 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c ght be more or l
2d520 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f ess than the amo
2d530 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a unt requested..*
2d540 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
2d550 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 lease_memory(int
2d560 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2d570 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d EF: Impose A Lim
2d580 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a it On Heap Size.
2d590 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2d5a0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
2d5b0 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 it() interface p
2d5c0 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c laces a "soft" l
2d5d0 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 imit.** on the a
2d5e0 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 mount of heap me
2d5f0 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 mory that may be
2d600 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
2d610 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 Lite..** ^If an
2d620 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 internal allocat
2d630 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 ion is requested
2d640 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 that would exce
2d650 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 ed the.** soft h
2d660 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 eap limit, [sqli
2d670 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2d680 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 ry()] is invoked
2d690 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 one or.** more
2d6a0 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 times to free up
2d6b0 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f some space befo
2d6c0 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f re the allocatio
2d6d0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a n is performed..
2d6e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69 74 **.** ^The limit
2d6f0 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 is called "soft
2d700 22 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 ", because if [s
2d710 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
2d720 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e emory()].** cann
2d730 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65 ot free sufficie
2d740 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 nt memory to pre
2d750 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 vent the limit f
2d760 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 rom being exceed
2d770 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 ed,.** the memor
2d780 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 y is allocated a
2d790 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 nyway and the cu
2d7a0 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 rrent operation
2d7b0 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 proceeds..**.**
2d7c0 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a ^A negative or z
2d7d0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 ero value for N
2d7e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 means that there
2d7f0 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 is no soft heap
2d800 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 limit and.** [s
2d810 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
2d820 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e emory()] will on
2d830 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 ly be called whe
2d840 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 n memory is exha
2d850 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 usted..** ^The d
2d860 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 efault value for
2d870 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
2d880 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a imit is zero..**
2d890 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b .** ^(SQLite mak
2d8a0 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 es a best effort
2d8b0 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f to honor the so
2d8c0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a ft heap limit..*
2d8d0 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 * But if the sof
2d8e0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e t heap limit can
2d8f0 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 not be honored,
2d900 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a execution will.*
2d910 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f * continue witho
2d920 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 ut error or noti
2d930 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69 fication.)^ Thi
2d940 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d s is why the lim
2d950 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 it is.** called
2d960 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 a "soft" limit.
2d970 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 It is advisory
2d980 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f only..**.** Prio
2d990 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 r to SQLite vers
2d9a0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 ion 3.5.0, this
2d9b0 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e routine only con
2d9c0 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d strained the mem
2d9d0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 ory.** allocated
2d9e0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 by a single thr
2d9f0 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 ead - the same t
2da00 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 hread in which t
2da10 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 his routine.** r
2da20 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 uns. Beginning
2da30 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 with SQLite vers
2da40 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 ion 3.5.0, the s
2da50 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 oft heap limit i
2da60 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 s.** applied to
2da70 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 all threads. The
2da80 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 value specified
2da90 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 for the soft he
2daa0 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 ap limit.** is a
2dab0 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e n upper bound on
2dac0 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 the total memor
2dad0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 y allocation for
2dae0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e all threads. In
2daf0 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e .** version 3.5.
2db00 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 0 there is no me
2db10 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 chanism for limi
2db20 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 ting the heap us
2db30 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 age for.** indiv
2db40 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a idual threads..*
2db50 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 /.void sqlite3_s
2db60 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 oft_heap_limit(i
2db70 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
2db80 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 3REF: Extract Me
2db90 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 tadata About A C
2dba0 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 olumn Of A Table
2dbb0 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 33 30 {H12850} <S6030
2dbc0 30 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 0>.**.** ^This r
2dbd0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d outine returns m
2dbe0 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 etadata about a
2dbf0 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 specific column
2dc00 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a of a specific.**
2dc10 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
2dc20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 accessible using
2dc30 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2dc40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
2dc50 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 e.** passed as t
2dc60 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f he first functio
2dc70 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a n argument..**.*
2dc80 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 * ^The column is
2dc90 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
2dca0 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 he second, third
2dcb0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 and fourth para
2dcc0 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 meters to.** thi
2dcd0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 28 54 68 s function. ^(Th
2dce0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
2dcf0 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 er is either the
2dd00 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
2dd10 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 abase.** (i.e. "
2dd20 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 main", "temp" or
2dd30 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 an attached dat
2dd40 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e abase) containin
2dd50 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a g the specified.
2dd60 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c ** table or NULL
2dd70 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c . If it is NULL,
2dd80 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 then all attach
2dd90 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 ed databases are
2dda0 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 searched.** for
2ddb0 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 the table using
2ddc0 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 the same algori
2ddd0 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 thm used by the
2dde0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 database engine
2ddf0 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e to.** resolve un
2de00 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 qualified table
2de10 72 65 66 65 72 65 6e 63 65 73 2e 29 5e 0a 2a 2a references.)^.**
2de20 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 .** ^The third a
2de30 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 nd fourth parame
2de40 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e ters to this fun
2de50 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 ction are the ta
2de60 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a ble and column.*
2de70 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 * name of the de
2de80 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 sired column, re
2de90 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 spectively. Neit
2dea0 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 her of these par
2deb0 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 ameters.** may b
2dec0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d e NULL..**.** ^M
2ded0 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 etadata is retur
2dee0 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 ned by writing t
2def0 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 o the memory loc
2df00 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 ations passed as
2df10 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 the 5th.** and
2df20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d subsequent param
2df30 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 eters to this fu
2df40 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 nction. ^Any of
2df50 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 these arguments
2df60 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 may be.** NULL,
2df70 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 in which case th
2df80 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
2df90 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 element of metad
2dfa0 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a ata is omitted..
2dfb0 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 **.** ^(<blockqu
2dfc0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 ote>.** <table b
2dfd0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 order="1">.** <t
2dfe0 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 r><th> Parameter
2dff0 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e <th> Output<br>
2e000 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 Type <th> Descr
2e010 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 iption.**.** <tr
2e020 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 ><td> 5th <td> c
2e030 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 onst char* <td>
2e040 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 Data type.** <tr
2e050 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 ><td> 6th <td> c
2e060 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 onst char* <td>
2e070 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 Name of default
2e080 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
2e090 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 ce.** <tr><td> 7
2e0a0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 th <td> int
2e0b0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 <td> True if
2e0c0 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f column has a NO
2e0d0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e T NULL constrain
2e0e0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 t.** <tr><td> 8t
2e0f0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 h <td> int
2e100 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 <td> True if
2e110 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f column is part o
2e120 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 f the PRIMARY KE
2e130 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 Y.** <tr><td> 9t
2e140 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 h <td> int
2e150 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 <td> True if
2e160 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 column is [AUTOI
2e170 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 NCREMENT].** </t
2e180 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b able>.** </block
2e190 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e quote>)^.**.** ^
2e1a0 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 The memory point
2e1b0 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 ed to by the cha
2e1c0 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 racter pointers
2e1d0 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 returned for the
2e1e0 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 .** declaration
2e1f0 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 type and collati
2e200 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 on sequence is v
2e210 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 alid only until
2e220 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c the next.** call
2e230 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 to any SQLite A
2e240 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a PI function..**.
2e250 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 ** ^If the speci
2e260 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 fied table is ac
2e270 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 tually a view, a
2e280 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
2e290 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
2e2a0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 * ^If the specif
2e2b0 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 ied column is "r
2e2c0 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 owid", "oid" or
2e2d0 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e "_rowid_" and an
2e2e0 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 .** [INTEGER PRI
2e2f0 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e MARY KEY] column
2e300 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 has been explic
2e310 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 itly declared, t
2e320 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a hen the output.*
2e330 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 * parameters are
2e340 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 set for the exp
2e350 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
2e360 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 column. ^(If th
2e370 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 ere is no.** exp
2e380 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
2e390 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 [INTEGER PRIMAR
2e3a0 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 Y KEY] column, t
2e3b0 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a hen the output.*
2e3c0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 * parameters are
2e3d0 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a set as follows:
2e3e0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 .**.** <pre>.**
2e3f0 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 data type: "
2e400 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 INTEGER".**
2e410 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
2e420 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 ce: "BINARY".**
2e430 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a not null: 0.
2e440 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b ** primary k
2e450 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 ey: 1.** aut
2e460 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a o increment: 0.*
2e470 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a * </pre>)^.**.**
2e480 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ^(This function
2e490 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 may load one or
2e4a0 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 more schemas fr
2e4b0 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 om database file
2e4c0 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f s. If an.** erro
2e4d0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 r occurs during
2e4e0 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 this process, or
2e4f0 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 if the requeste
2e500 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d d table or colum
2e510 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 n.** cannot be f
2e520 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 ound, an [error
2e530 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
2e540 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d d and an error m
2e550 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 essage left.** i
2e560 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
2e570 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 connection] (to
2e580 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 be retrieved usi
2e590 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 ng sqlite3_errms
2e5a0 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 g()).)^.**.** ^T
2e5b0 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 his API is only
2e5c0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 available if the
2e5d0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d library was com
2e5e0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
2e5f0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
2e600 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 _COLUMN_METADATA
2e610 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C-preprocessor
2e620 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e symbol defined.
2e630 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2e640 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 table_column_met
2e650 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 adata(. sqlite3
2e660 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2e670 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 /* Connecti
2e680 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 on handle */. c
2e690 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 onst char *zDbNa
2e6a0 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 me, /* Da
2e6b0 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e tabase name or N
2e6c0 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ULL */. const c
2e6d0 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c har *zTableName,
2e6e0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 /* Table na
2e6f0 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 me */. const ch
2e700 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c ar *zColumnName,
2e710 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 /* Column na
2e720 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e me */. char con
2e730 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c st **pzDataType,
2e740 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 /* OUTPUT: D
2e750 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 eclared data typ
2e760 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 e */. char cons
2e770 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 t **pzCollSeq,
2e780 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f /* OUTPUT: Co
2e790 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
2e7a0 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a name */. int *
2e7b0 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 pNotNull,
2e7c0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 /* OUTPUT
2e7d0 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 : True if NOT NU
2e7e0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 LL constraint ex
2e7f0 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 ists */. int *p
2e800 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 PrimaryKey,
2e810 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
2e820 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
2e830 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 part of PK */.
2e840 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 int *pAutoinc
2e850 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f /* O
2e860 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 UTPUT: True if c
2e870 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e olumn is auto-in
2e880 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f crement */.);../
2e890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
2e8a0 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e oad An Extension
2e8b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 .**.** ^This int
2e8c0 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 erface loads an
2e8d0 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e SQLite extension
2e8e0 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 library from th
2e8f0 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a e named file..**
2e900 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2e910 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
2e920 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
2e930 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a mpts to load an.
2e940 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 ** SQLite extens
2e950 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 ion library cont
2e960 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c ained in the fil
2e970 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e e zFile..**.** ^
2e980 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 The entry point
2e990 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 is zProc..** ^zP
2e9a0 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e roc may be 0, in
2e9b0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 which case the
2e9c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 name of the entr
2e9d0 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 y point.** defau
2e9e0 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f lts to "sqlite3_
2e9f0 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e extension_init".
2ea00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2ea10 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
2ea20 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2ea30 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f rns.** [SQLITE_O
2ea40 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e K] on success an
2ea50 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d d [SQLITE_ERROR]
2ea60 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f if something go
2ea70 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 es wrong..** ^If
2ea80 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
2ea90 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 and pzErrMsg is
2eaa0 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 not 0, then the
2eab0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 .** [sqlite3_loa
2eac0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 d_extension()] i
2ead0 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 nterface shall a
2eae0 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c ttempt to.** fil
2eaf0 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 l *pzErrMsg with
2eb00 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 error message t
2eb10 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 ext stored in me
2eb20 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 mory.** obtained
2eb30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
2eb40 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 alloc()]. The ca
2eb50 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a lling function.*
2eb60 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 * should free th
2eb70 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c is memory by cal
2eb80 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 ling [sqlite3_fr
2eb90 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 ee()]..**.** ^Ex
2eba0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 tension loading
2ebb0 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 must be enabled
2ebc0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
2ebd0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 3_enable_load_ex
2ebe0 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 tension()] prior
2ebf0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 to calling this
2ec00 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 API,.** otherwi
2ec10 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c se an error will
2ec20 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a be returned..**
2ec30 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 .** See also the
2ec40 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e [load_extension
2ec50 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
2ec60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2ec70 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
2ec80 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2ec90 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 /* Load
2eca0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 the extension i
2ecb0 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 nto this databas
2ecc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a e connection */.
2ecd0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 const char *zF
2ece0 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 ile, /* Name
2ecf0 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 of the shared li
2ed00 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 brary containing
2ed10 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 extension */.
2ed20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f const char *zPro
2ed30 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 c, /* Entry p
2ed40 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 oint. Derived f
2ed50 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a rom zFile if 0 *
2ed60 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 /. char **pzErr
2ed70 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 Msg /* Put
2ed80 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 error message h
2ed90 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a ere if not 0 */.
2eda0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2edb0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 EF: Enable Or Di
2edc0 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 sable Extension
2edd0 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 Loading.**.** ^S
2ede0 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e o as not to open
2edf0 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 security holes
2ee00 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 in older applica
2ee10 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a tions that are.*
2ee20 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 * unprepared to
2ee30 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 deal with extens
2ee40 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 ion loading, and
2ee50 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 as a means of d
2ee60 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 isabling.** exte
2ee70 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 nsion loading wh
2ee80 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 ile evaluating u
2ee90 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c ser-entered SQL,
2eea0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 the following A
2eeb0 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 PI.** is provide
2eec0 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 d to turn the [s
2eed0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
2eee0 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 nsion()] mechani
2eef0 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a sm on and off..*
2ef00 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 *.** ^Extension
2ef10 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 loading is off b
2ef20 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 y default. See t
2ef30 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 icket #1863..**
2ef40 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 ^Call the sqlite
2ef50 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 3_enable_load_ex
2ef60 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e tension() routin
2ef70 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a e with onoff==1.
2ef80 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e ** to turn exten
2ef90 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 sion loading on
2efa0 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 and call it with
2efb0 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 onoff==0 to tur
2efc0 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 n.** it back off
2efd0 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 again..*/.int s
2efe0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f qlite3_enable_lo
2eff0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c ad_extension(sql
2f000 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e ite3 *db, int on
2f010 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 off);../*.** CAP
2f020 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 I3REF: Automatic
2f030 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 ally Load An Ext
2f040 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 ensions.**.** ^T
2f050 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 his API can be i
2f060 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 nvoked at progra
2f070 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 m startup in ord
2f080 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a er to register.*
2f090 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 * one or more st
2f0a0 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 atically linked
2f0b0 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 extensions that
2f0c0 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c will be availabl
2f0d0 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 e.** to all new
2f0e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2f0f0 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 tions]..**.** ^(
2f100 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f This routine sto
2f110 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f res a pointer to
2f120 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 the extension e
2f130 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e ntry point.** in
2f140 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 an array that i
2f150 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 s obtained from
2f160 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
2f170 29 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 )]. That memory
2f180 0a 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 .** is deallocat
2f190 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 ed by [sqlite3_r
2f1a0 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 eset_auto_extens
2f1b0 69 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 ion()].)^.**.**
2f1c0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 ^This function r
2f1d0 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 egisters an exte
2f1e0 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e nsion entry poin
2f1f0 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 t that is.** aut
2f200 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b omatically invok
2f210 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 ed whenever a ne
2f220 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e w [database conn
2f230 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 ection].** is op
2f240 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ened using [sqli
2f250 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
2f260 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c lite3_open16()],
2f270 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
2f280 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e open_v2()]..** ^
2f290 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 Duplicate extens
2f2a0 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 ions are detecte
2f2b0 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 d so calling thi
2f2c0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c s routine.** mul
2f2d0 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 tiple times with
2f2e0 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 the same extens
2f2f0 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e ion is harmless.
2f300 0a 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 .** ^Automatic e
2f310 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 xtensions apply
2f320 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 across all threa
2f330 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ds..*/.int sqlit
2f340 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f e3_auto_extensio
2f350 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 n(void (*xEntryP
2f360 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f oint)(void));../
2f370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2f380 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 eset Automatic E
2f390 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 xtension Loading
2f3a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 .**.** ^(This fu
2f3b0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 nction disables
2f3c0 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 all previously r
2f3d0 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 egistered automa
2f3e0 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e tic.** extension
2f3f0 73 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 s. It undoes the
2f400 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 effect of all p
2f410 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 rior.** [sqlite3
2f420 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 _auto_extension(
2f430 29 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a )] calls.)^.**.*
2f440 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
2f450 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 disables automa
2f460 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 tic extensions i
2f470 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a n all threads..*
2f480 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 /.void sqlite3_r
2f490 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 eset_auto_extens
2f4a0 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a ion(void);../*.*
2f4b0 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ***** EXPERIMENT
2f4c0 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 AL - subject to
2f4d0 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e change without n
2f4e0 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a otice **********
2f4f0 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ****.**.** The i
2f500 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 nterface to the
2f510 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
2f520 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 chanism is curre
2f530 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a ntly considered.
2f540 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d ** to be experim
2f550 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 ental. The inte
2f560 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e rface might chan
2f570 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 ge in incompatib
2f580 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 le ways..** If t
2f590 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d his is a problem
2f5a0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 for you, do not
2f5b0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 use the interfa
2f5c0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e ce at this time.
2f5d0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
2f5e0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
2f5f0 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a chanism stabiliz
2f600 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c es, we will decl
2f610 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 are the.** inter
2f620 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 face fixed, supp
2f630 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 ort it indefinit
2f640 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 ely, and remove
2f650 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f this comment..*/
2f660 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 ../*.** Structur
2f670 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 es used by the v
2f680 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 irtual table int
2f690 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 erface.*/.typede
2f6a0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
2f6b0 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 _vtab sqlite3_vt
2f6c0 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 ab;.typedef stru
2f6d0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
2f6e0 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e _info sqlite3_in
2f6f0 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 dex_info;.typede
2f700 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
2f710 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c _vtab_cursor sql
2f720 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
2f730 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 ;.typedef struct
2f740 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
2f750 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a sqlite3_module;.
2f760 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2f770 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f Virtual Table O
2f780 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
2f790 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c S: sqlite3_modul
2f7a0 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 e {virtual table
2f7b0 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45 module}.** EXPE
2f7c0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
2f7d0 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 his structure, s
2f7e0 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 ometimes called
2f7f0 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 a a "virtual tab
2f800 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 le module", .**
2f810 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c defines the impl
2f820 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 ementation of a
2f830 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d [virtual tables]
2f840 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 . .** This stru
2f850 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d cture consists m
2f860 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 ostly of methods
2f870 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
2f880 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 .**.** ^A virtua
2f890 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 l table module i
2f8a0 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c s created by fil
2f8b0 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 ling in a persis
2f8c0 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 tent.** instance
2f8d0 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 of this structu
2f8e0 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 re and passing a
2f8f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 pointer to that
2f900 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 instance.** to
2f910 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2f920 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 module()] or [sq
2f930 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
2f940 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 ule_v2()]..** ^T
2f950 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 he registration
2f960 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e remains valid un
2f970 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 til it is replac
2f980 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e ed by a differen
2f990 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 t.** module or u
2f9a0 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 ntil the [databa
2f9b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 se connection] c
2f9c0 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 loses. The cont
2f9d0 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 ent.** of this s
2f9e0 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f tructure must no
2f9f0 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 t change while i
2fa00 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 t is registered
2fa10 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 with.** any data
2fa20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
2fa30 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
2fa40 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e e3_module {. in
2fa50 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
2fa60 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c t (*xCreate)(sql
2fa70 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 ite3*, void *pAu
2fa80 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 x,.
2fa90 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 int argc, cons
2faa0 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 t char *const*ar
2fab0 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 gv,.
2fac0 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 sqlite3_vtab
2fad0 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a **ppVTab, char**
2fae0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e );. int (*xConn
2faf0 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 ect)(sqlite3*, v
2fb00 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 oid *pAux,.
2fb10 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
2fb20 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a gc, const char *
2fb30 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 const*argv,.
2fb40 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 sqlit
2fb50 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 e3_vtab **ppVTab
2fb60 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 , char**);. int
2fb70 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 (*xBestIndex)(s
2fb80 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2fb90 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 ab, sqlite3_inde
2fba0 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 x_info*);. int
2fbb0 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 (*xDisconnect)(s
2fbc0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2fbd0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 ab);. int (*xDe
2fbe0 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 stroy)(sqlite3_v
2fbf0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
2fc00 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
2fc10 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c te3_vtab *pVTab,
2fc20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
2fc30 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 rsor **ppCursor)
2fc40 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 ;. int (*xClose
2fc50 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
2fc60 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 ursor*);. int (
2fc70 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 *xFilter)(sqlite
2fc80 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 3_vtab_cursor*,
2fc90 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 int idxNum, cons
2fca0 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a t char *idxStr,.
2fcb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2fcc0 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 int argc, sqlite
2fcd0 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 3_value **argv);
2fce0 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 . int (*xNext)(
2fcf0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
2fd00 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
2fd10 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 Eof)(sqlite3_vta
2fd20 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
2fd30 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c t (*xColumn)(sql
2fd40 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
2fd50 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 *, sqlite3_conte
2fd60 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 xt*, int);. int
2fd70 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 (*xRowid)(sqlit
2fd80 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
2fd90 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
2fda0 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 pRowid);. int (
2fdb0 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 *xUpdate)(sqlite
2fdc0 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 3_vtab *, int, s
2fdd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c qlite3_value **,
2fde0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
2fdf0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 );. int (*xBegi
2fe00 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
2fe10 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
2fe20 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
2fe30 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2fe40 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 int (*xCommit)(s
2fe50 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2fe60 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f ab);. int (*xRo
2fe70 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f llback)(sqlite3_
2fe80 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2fe90 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 int (*xFindFunct
2fea0 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ion)(sqlite3_vta
2feb0 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 b *pVtab, int nA
2fec0 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a rg, const char *
2fed0 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 zName,.
2fee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
2fef0 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 id (**pxFunc)(sq
2ff00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
2ff10 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
2ff20 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 **),.
2ff30 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
2ff40 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 **ppArg);. int
2ff50 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 (*xRename)(sqli
2ff60 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c te3_vtab *pVtab,
2ff70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 const char *zNe
2ff80 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 w);.};../*.** CA
2ff90 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
2ffa0 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 Table Indexing I
2ffb0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 nformation.** KE
2ffc0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
2ffd0 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 index_info.** EX
2ffe0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
2fff0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 The sqlite3_ind
30000 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 ex_info structur
30010 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 e and its substr
30020 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 uctures is used
30030 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 to.** pass infor
30040 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 mation into and
30050 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c receive the repl
30060 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 y from the [xBes
30070 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f tIndex].** metho
30080 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 d of a [virtual
30090 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 table module].
300a0 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 The fields under
300b0 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 **Inputs** are
300c0 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f the.** inputs to
300d0 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 xBestIndex and
300e0 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 are read-only.
300f0 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 xBestIndex inser
30100 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 ts its.** result
30110 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 s into the **Out
30120 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a puts** fields..*
30130 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73 *.** ^(The aCons
30140 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 traint[] array r
30150 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 ecords WHERE cla
30160 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 use constraints
30170 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a of the form:.**.
30180 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f ** <pre>column O
30190 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a P expr</pre>.**.
301a0 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d ** where OP is =
301b0 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 , <, <=, &
301c0 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e gt;, or >=.)^
301d0 20 20 5e 54 68 65 20 70 61 72 74 69 63 75 6c 61 ^The particula
301e0 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a r operator is.**
301f0 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 stored in aCons
30200 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 5e 54 traint[].op. ^T
30210 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
30220 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 column is stored
30230 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 in.** aConstrai
30240 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 5e nt[].iColumn. ^
30250 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 (aConstraint[].u
30260 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 sable is TRUE if
30270 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 the.** expr on
30280 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 the right-hand s
30290 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 ide can be evalu
302a0 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 ated (and thus t
302b0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a he constraint.**
302c0 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 is usable) and
302d0 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e false if it cann
302e0 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ot.)^.**.** ^The
302f0 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d optimizer autom
30300 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 atically inverts
30310 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f terms of the fo
30320 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 rm "expr OP colu
30330 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 mn".** and makes
30340 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 other simplific
30350 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 ations to the WH
30360 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e ERE clause in an
30370 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 attempt to.** g
30380 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 et as many WHERE
30390 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e clause terms in
303a0 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 to the form show
303b0 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 n above as possi
303c0 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f ble..** ^The aCo
303d0 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 nstraint[] array
303e0 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 only reports WH
303f0 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 ERE clause terms
30400 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a in the correct.
30410 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 ** form that ref
30420 65 72 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 er to the partic
30430 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 ular virtual tab
30440 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 le being queried
30450 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 ..**.** ^Informa
30460 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f tion about the O
30470 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 RDER BY clause i
30480 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 s stored in aOrd
30490 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 erBy[]..** ^Each
304a0 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 term of aOrderB
304b0 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 y records a colu
304c0 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 mn of the ORDER
304d0 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a BY clause..**.**
304e0 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 The [xBestIndex
304f0 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 ] method must fi
30500 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 ll aConstraintUs
30510 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 age[] with infor
30520 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 mation.** about
30530 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 what parameters
30540 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 to pass to xFilt
30550 65 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 er. ^If argvInd
30560 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 ex>0 then.** the
30570 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 right-hand side
30580 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f of the correspo
30590 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e nding aConstrain
305a0 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 t[] is evaluated
305b0 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 .** and becomes
305c0 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 the argvIndex-th
305d0 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 entry in argv.
305e0 20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e ^(If aConstrain
305f0 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a tUsage[].omit.**
30600 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 is true, then t
30610 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 he constraint is
30620 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 assumed to be f
30630 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 ully handled by
30640 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 the.** virtual t
30650 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 able and is not
30660 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 checked again by
30670 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a SQLite.)^.**.**
30680 20 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 ^The idxNum and
30690 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 idxPtr values a
306a0 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 re recorded and
306b0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a passed into the.
306c0 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 ** [xFilter] met
306d0 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 hod..** ^[sqlite
306e0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 3_free()] is use
306f0 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 d to free idxPtr
30700 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 66 if and only iff
30710 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 .** needToFreeId
30720 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a xPtr is true..**
30730 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 .** ^The orderBy
30740 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 Consumed means t
30750 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 hat output from
30760 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 [xFilter]/[xNext
30770 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a ] will occur in.
30780 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f ** the correct o
30790 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 rder to satisfy
307a0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
307b0 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 use so that no s
307c0 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 eparate.** sorti
307d0 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 ng step is requi
307e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 red..**.** ^The
307f0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 estimatedCost va
30800 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 lue is an estima
30810 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f te of the cost o
30820 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 f doing the.** p
30830 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 articular lookup
30840 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f . A full scan o
30850 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e f a table with N
30860 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 entries should
30870 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f have.** a cost o
30880 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 f N. A binary s
30890 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 earch of a table
308a0 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 of N entries sh
308b0 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 ould have a.** c
308c0 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 ost of approxima
308d0 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a tely log(N)..*/.
308e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
308f0 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a ndex_info {. /*
30900 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 Inputs */. int
30910 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 nConstraint;
30920 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
30930 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 r of entries in
30940 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 aConstraint */.
30950 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
30960 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 index_constraint
30970 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c {. int iCol
30980 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 umn;
30990 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c /* Column on l
309a0 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 eft-hand side of
309b0 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 constraint */.
309c0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 unsigned cha
309d0 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a r op; /*
309e0 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 Constraint oper
309f0 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 ator */. uns
30a00 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c igned char usabl
30a10 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 e; /* True i
30a20 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e f this constrain
30a30 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 t is usable */.
30a40 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 int iTermOff
30a50 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a set; /*
30a60 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 Used internally
30a70 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 - xBestIndex sh
30a80 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 ould ignore */.
30a90 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b } *aConstraint;
30aa0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 /* T
30ab0 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c able of WHERE cl
30ac0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 ause constraints
30ad0 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 */. int nOrder
30ae0 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 By;
30af0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 /* Number of te
30b00 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 rms in the ORDER
30b10 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 BY clause */.
30b20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
30b30 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 ndex_orderby {.
30b40 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b int iColumn;
30b50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
30b60 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a Column number *
30b70 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 /. unsigned
30b80 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 char desc;
30b90 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 /* True for DES
30ba0 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 C. False for AS
30bb0 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 C. */. } *aOrde
30bc0 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 rBy;
30bd0 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 /* The ORDER
30be0 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f BY clause */. /
30bf0 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 * Outputs */. s
30c00 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
30c10 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 dex_constraint_u
30c20 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 sage {. int a
30c30 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 rgvIndex;
30c40 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f /* if >0, co
30c50 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 nstraint is part
30c60 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c of argv to xFil
30c70 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 ter */. unsig
30c80 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 ned char omit;
30c90 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f /* Do not co
30ca0 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 de a test for th
30cb0 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f is constraint */
30cc0 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e . } *aConstrain
30cd0 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 tUsage;. int id
30ce0 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 xNum;
30cf0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 /* Number u
30d00 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 sed to identify
30d10 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 the index */. c
30d20 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 har *idxStr;
30d30 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 /* Str
30d40 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 ing, possibly ob
30d50 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 tained from sqli
30d60 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 te3_malloc */.
30d70 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 int needToFreeId
30d80 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 xStr; /* Fr
30d90 65 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 ee idxStr using
30da0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
30db0 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 f true */. int
30dc0 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b orderByConsumed;
30dd0 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 /* True i
30de0 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 f output is alre
30df0 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 ady ordered */.
30e00 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 double estimate
30e10 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 dCost; /* E
30e20 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 stimated cost of
30e30 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 using this inde
30e40 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 x */.};.#define
30e50 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
30e60 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a STRAINT_EQ 2.
30e70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
30e80 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
30e90 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 GT 4.#define
30ea0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
30eb0 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a STRAINT_LE 8.
30ec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
30ed0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
30ee0 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 LT 16.#define
30ef0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
30f00 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 NSTRAINT_GE 3
30f10 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
30f20 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
30f30 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a T_MATCH 64../*.*
30f40 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 * CAPI3REF: Regi
30f50 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 ster A Virtual T
30f60 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 able Implementat
30f70 69 6f 6e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e ion.** EXPERIMEN
30f80 54 41 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 TAL.**.** ^This
30f90 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 routine is used
30fa0 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 to register a ne
30fb0 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 w [virtual table
30fc0 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a module] name..*
30fd0 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 * ^Module names
30fe0 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 must be register
30ff0 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 ed before.** cre
31000 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 ating a new [vir
31010 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e tual table] usin
31020 67 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 g the module, or
31030 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a before using a.
31040 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b ** preexisting [
31050 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 virtual table] f
31060 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a or the module..*
31070 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 *.** ^The module
31080 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 name is registe
31090 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 red on the [data
310a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
310b0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
310c0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
310d0 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 eter. ^The name
310e0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 of the module i
310f0 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a s given by the .
31100 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
31110 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64 ter. ^The third
31120 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
31130 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 pointer to.** th
31140 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
31150 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c of the [virtual
31160 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 table module].
31170 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a ^The fourth.**
31180 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e parameter is an
31190 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e arbitrary clien
311a0 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 t data pointer t
311b0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68 hat is passed th
311c0 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 rough.** into th
311d0 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 e [xCreate] and
311e0 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f [xConnect] metho
311f0 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 ds of the virtua
31200 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a l table module.*
31210 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 * when a new vir
31220 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 tual table is be
31230 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f being created o
31240 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e r reinitialized.
31250 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 .**.** ^This int
31260 65 72 66 61 63 65 20 68 61 73 20 65 78 61 63 74 erface has exact
31270 6c 79 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 ly the same effe
31280 63 74 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a ct as calling.**
31290 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
312a0 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 20 77 69 _module_v2()] wi
312b0 74 68 20 61 20 4e 55 4c 4c 20 63 6c 69 65 6e 74 th a NULL client
312c0 20 64 61 74 61 20 64 65 73 74 72 75 63 74 6f 72 data destructor
312d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 ..*/.SQLITE_EXPE
312e0 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c RIMENTAL int sql
312f0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
31300 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 le(. sqlite3 *d
31310 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
31320 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 /* SQLite conne
31330 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 ction to registe
31340 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f r module with */
31350 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
31360 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a Name, /*
31370 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 Name of the mod
31380 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 ule */. const s
31390 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 qlite3_module *p
313a0 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 , /* Methods f
313b0 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f or the module */
313c0 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 . void *pClient
313d0 44 61 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a Data /*
313e0 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 Client data for
313f0 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 xCreate/xConnec
31400 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t */.);../*.** C
31410 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 API3REF: Registe
31420 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c r A Virtual Tabl
31430 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e Implementation
31440 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
31450 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
31460 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 tine is identica
31470 6c 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 l to the [sqlite
31480 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 3_create_module(
31490 29 5d 20 6d 65 74 68 6f 64 2c 0a 2a 2a 20 65 78 )] method,.** ex
314a0 63 65 70 74 20 74 68 61 74 20 69 74 20 68 61 73 cept that it has
314b0 20 61 6e 20 65 78 74 72 61 20 70 61 72 61 6d 65 an extra parame
314c0 74 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 0a ter to specify .
314d0 2a 2a 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 ** a destructor
314e0 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 function for the
314f0 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 client data poi
31500 6e 74 65 72 2e 20 20 5e 53 51 4c 69 74 65 20 77 nter. ^SQLite w
31510 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 ill.** invoke th
31520 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e e destructor fun
31530 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 ction (if it is
31540 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 not NULL) when S
31550 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 QLite.** no long
31560 65 72 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c er needs the pCl
31570 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 ientData pointer
31580 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 . .*/.SQLITE_EX
31590 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
315a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
315b0 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 dule_v2(. sqlit
315c0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
315d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 /* SQLite
315e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 connection to re
315f0 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 gister module wi
31600 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 th */. const ch
31610 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 ar *zName,
31620 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
31630 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f e module */. co
31640 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 nst sqlite3_modu
31650 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 le *p, /* Meth
31660 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 ods for the modu
31670 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 le */. void *pC
31680 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20 lientData,
31690 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 /* Client dat
316a0 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 a for xCreate/xC
316b0 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 onnect */. void
316c0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
316d0 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 *) /* Module
316e0 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 destructor func
316f0 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a tion */.);../*.*
31700 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 * CAPI3REF: Virt
31710 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e ual Table Instan
31720 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 ce Object.** KEY
31730 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 WORDS: sqlite3_v
31740 74 61 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e tab.** EXPERIMEN
31750 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 TAL.**.** Every
31760 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d [virtual table m
31770 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 odule] implement
31780 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 ation uses a sub
31790 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73 class.** of this
317a0 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63 72 object to descr
317b0 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 ibe a particular
317c0 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 instance.** of
317d0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 the [virtual tab
317e0 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63 6c le]. Each subcl
317f0 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 ass will.** be t
31800 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 ailored to the s
31810 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 pecific needs of
31820 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c the module impl
31830 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 ementation..** T
31840 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 he purpose of th
31850 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 is superclass is
31860 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 to define certa
31870 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 in fields that a
31880 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 re.** common to
31890 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 all module imple
318a0 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a mentations..**.*
318b0 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c 65 * ^Virtual table
318c0 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 s methods can se
318d0 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 t an error messa
318e0 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 ge by assigning
318f0 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 a.** string obta
31900 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
31910 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f e3_mprintf()] to
31920 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d zErrMsg. The m
31930 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 ethod should.**
31940 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61 take care that a
31950 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 ny prior string
31960 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61 is freed by a ca
31970 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ll to [sqlite3_f
31980 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 ree()].** prior
31990 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e to assigning a n
319a0 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 ew string to zEr
319b0 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74 68 rMsg. ^After th
319c0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a e error message.
319d0 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 ** is delivered
319e0 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 up to the client
319f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 application, th
31a00 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 e string will be
31a10 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
31a20 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 * freed by sqlit
31a30 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 e3_free() and th
31a40 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 e zErrMsg field
31a50 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a will be zeroed..
31a60 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
31a70 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 3_vtab {. const
31a80 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
31a90 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 *pModule; /* Th
31aa0 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 e module for thi
31ab0 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 s virtual table
31ac0 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 */. int nRef;
31ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
31ae0 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 /* NO LONGE
31af0 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72 R USED */. char
31b00 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 *zErrMsg;
31b10 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 /* E
31b20 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f rror message fro
31b30 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 m sqlite3_mprint
31b40 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 f() */. /* Virt
31b50 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d ual table implem
31b60 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 entations will t
31b70 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 ypically add add
31b80 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a itional fields *
31b90 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
31ba0 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 3REF: Virtual Ta
31bb0 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 ble Cursor Objec
31bc0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 t.** KEYWORDS: s
31bd0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
31be0 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c or {virtual tabl
31bf0 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 20 45 58 50 e cursor}.** EXP
31c00 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
31c10 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 Every [virtual t
31c20 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 able module] imp
31c30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 lementation uses
31c40 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 a subclass of t
31c50 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 he.** following
31c60 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 structure to des
31c70 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 cribe cursors th
31c80 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 at point into th
31c90 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 e.** [virtual ta
31ca0 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65 ble] and are use
31cb0 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 d.** to loop thr
31cc0 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c ough the virtual
31cd0 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 table. Cursors
31ce0 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 are created usi
31cf0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
31d00 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 e3_module.xOpen
31d10 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 | xOpen] method
31d20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e of the module an
31d30 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a d are destroyed.
31d40 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ** by the [sqlit
31d50 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 e3_module.xClose
31d60 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f | xClose] metho
31d70 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 d. Cursors are
31d80 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b used.** by the [
31d90 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 xFilter], [xNext
31da0 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c ], [xEof], [xCol
31db0 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 umn], and [xRowi
31dc0 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 d] methods.** of
31dd0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 the module. Ea
31de0 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d ch module implem
31df0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 entation will de
31e00 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 fine.** the cont
31e10 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 ent of a cursor
31e20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 structure to sui
31e30 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e t its own needs.
31e40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 .**.** This supe
31e50 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e rclass exists in
31e60 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 order to define
31e70 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 fields of the c
31e80 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 ursor that.** ar
31e90 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 e common to all
31ea0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e implementations.
31eb0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
31ec0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b e3_vtab_cursor {
31ed0 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 . sqlite3_vtab
31ee0 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 *pVtab; /*
31ef0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 Virtual table of
31f00 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a this cursor */.
31f10 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 /* Virtual tab
31f20 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
31f30 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c ns will typicall
31f40 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c y add additional
31f50 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f fields */.};../
31f60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
31f70 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d eclare The Schem
31f80 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 a Of A Virtual T
31f90 61 62 6c 65 0a 2a 2a 20 45 58 50 45 52 49 4d 45 able.** EXPERIME
31fa0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 NTAL.**.** ^The
31fb0 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 [xCreate] and [x
31fc0 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 Connect] methods
31fd0 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 of a.** [virtua
31fe0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 l table module]
31ff0 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66 call this interf
32000 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 ace.** to declar
32010 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 e the format (th
32020 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 e names and data
32030 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c types of the col
32040 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 umns) of.** the
32050 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 virtual tables t
32060 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a hey implement..*
32070 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d /.SQLITE_EXPERIM
32080 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 ENTAL int sqlite
32090 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 3_declare_vtab(s
320a0 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 qlite3*, const c
320b0 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a har *zSQL);../*.
320c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 ** CAPI3REF: Ove
320d0 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e rload A Function
320e0 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 For A Virtual T
320f0 61 62 6c 65 0a 2a 2a 20 45 58 50 45 52 49 4d 45 able.** EXPERIME
32100 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 NTAL.**.** ^(Vir
32110 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 tual tables can
32120 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 provide alternat
32130 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ive implementati
32140 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 ons of functions
32150 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 .** using the [x
32160 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 FindFunction] me
32170 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 thod of the [vir
32180 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
32190 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f e]. .** But glo
321a0 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 bal versions of
321b0 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a those functions.
321c0 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e ** must exist in
321d0 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 order to be ove
321e0 72 6c 6f 61 64 65 64 2e 29 0a 2a 2a 0a 2a 2a 20 rloaded.).**.**
321f0 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 ^(This API makes
32200 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 sure a global v
32210 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 ersion of a func
32220 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 tion with a part
32230 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 icular.** name a
32240 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 nd number of par
32250 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 ameters exists.
32260 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 If no such func
32270 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 tion exists.** b
32280 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 efore this API i
32290 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 s called, a new
322a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 function is crea
322b0 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70 ted.)^ ^The imp
322c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f lementation.** o
322d0 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 f the new functi
322e0 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 on always causes
322f0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f an exception to
32300 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a be thrown. So.
32310 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 ** the new funct
32320 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 ion is not good
32330 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 for anything by
32340 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c itself. Its onl
32350 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 y.** purpose is
32360 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c to be a placehol
32370 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 der function tha
32380 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 t can be overloa
32390 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 ded.** by a [vir
323a0 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a tual table]..*/.
323b0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
323c0 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TAL int sqlite3_
323d0 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f overload_functio
323e0 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 n(sqlite3*, cons
323f0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d t char *zFuncNam
32400 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f e, int nArg);../
32410 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 *.** The interfa
32420 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 ce to the virtua
32430 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 l-table mechanis
32440 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 m defined above
32450 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 (back up.** to a
32460 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 comment remarka
32470 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 bly similar to t
32480 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 his one) is curr
32490 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 ently considered
324a0 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 .** to be experi
324b0 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 mental. The int
324c0 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 erface might cha
324d0 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 nge in incompati
324e0 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 ble ways..** If
324f0 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 this is a proble
32500 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f m for you, do no
32510 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 t use the interf
32520 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 ace at this time
32530 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
32540 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d virtual-table m
32550 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 echanism stabili
32560 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 zes, we will dec
32570 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 lare the.** inte
32580 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 rface fixed, sup
32590 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 port it indefini
325a0 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 tely, and remove
325b0 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a this comment..*
325c0 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d *.****** EXPERIM
325d0 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 ENTAL - subject
325e0 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
325f0 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a t notice *******
32600 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a *******.*/../*.*
32610 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 * CAPI3REF: A Ha
32620 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 ndle To An Open
32630 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 BLOB.** KEYWORDS
32640 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 : {BLOB handle}
32650 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a {BLOB handles}.*
32660 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
32670 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
32680 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 represents an op
32690 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 en BLOB on which
326a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
326b0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 b_open | increme
326c0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 ntal BLOB I/O] c
326d0 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e an be performed.
326e0 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20 .** ^Objects of
326f0 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 this type are cr
32700 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eated by [sqlite
32710 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 3_blob_open()].*
32720 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 * and destroyed
32730 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 by [sqlite3_blob
32740 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 _close()]..** ^T
32750 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
32760 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 _read()] and [sq
32770 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 lite3_blob_write
32780 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a ()] interfaces.*
32790 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f * can be used to
327a0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 read or write s
327b0 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 mall subsections
327c0 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a of the BLOB..**
327d0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 ^The [sqlite3_b
327e0 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 lob_bytes()] int
327f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
32800 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 he size of the B
32810 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f LOB in bytes..*/
32820 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
32830 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c sqlite3_blob sql
32840 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a ite3_blob;../*.*
32850 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e * CAPI3REF: Open
32860 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 A BLOB For Incr
32870 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 emental I/O {H17
32880 38 31 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 810} <S30230>.**
32890 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 .** ^(This inter
328a0 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 faces opens a [B
328b0 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e LOB handle | han
328c0 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 dle] to the BLOB
328d0 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 located.** in r
328e0 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 ow iRow, column
328f0 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a zColumn, table z
32900 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 Table in databas
32910 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 e zDb;.** in oth
32920 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 er words, the sa
32930 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 me BLOB that wou
32940 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 ld be selected b
32950 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a y:.**.** <pre>.*
32960 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f * SELECT zCo
32970 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 lumn FROM zDb.zT
32980 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 able WHERE [rowi
32990 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f d] = iRow;.** </
329a0 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 pre>)^.**.** ^If
329b0 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d the flags param
329c0 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f eter is non-zero
329d0 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 , then the BLOB
329e0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
329f0 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 ad.** and write
32a00 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74 20 69 access. ^If it i
32a10 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 s zero, the BLOB
32a20 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
32a30 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 5e ead access..** ^
32a40 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 It is not possib
32a50 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c le to open a col
32a60 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 umn that is part
32a70 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 of an index or
32a80 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 primary .** key
32a90 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 for writing. ^If
32aa0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f [foreign key co
32ab0 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65 nstraints] are e
32ac0 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a nabled, it is .*
32ad0 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 * not possible t
32ae0 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 o open a column
32af0 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 that is part of
32b00 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f a [child key] fo
32b10 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a r writing..**.**
32b20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 ^Note that the
32b30 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 database name is
32b40 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d not the filenam
32b50 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a e that contains.
32b60 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
32b70 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20 73 but rather the s
32b80 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 ymbolic name of
32b90 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 the database tha
32ba0 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61 66 74 t.** appears aft
32bb0 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 er the AS keywor
32bc0 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 d when the datab
32bd0 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 ase is connected
32be0 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e using [ATTACH].
32bf0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61 69 .** ^For the mai
32c00 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c n database file,
32c10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
32c20 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a me is "main"..**
32c30 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 ^For TEMP table
32c40 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 s, the database
32c50 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a name is "temp"..
32c60 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 **.** ^(On succe
32c70 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 ss, [SQLITE_OK]
32c80 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
32c90 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 the new [BLOB ha
32ca0 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e ndle] is written
32cb0 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 .** to *ppBlob.
32cc0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 Otherwise an [er
32cd0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
32ce0 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f urned and *ppBlo
32cf0 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 b is set.** to b
32d00 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 e a null pointer
32d10 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .)^.** ^This fun
32d20 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b ction sets the [
32d30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
32d40 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 ion] error code
32d50 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 and message.** a
32d60 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 ccessible via [s
32d70 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
32d80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 ] and [sqlite3_e
32d90 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c rrmsg()] and rel
32da0 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ated.** function
32db0 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 s. ^Note that th
32dc0 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62 e *ppBlob variab
32dd0 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69 le is always ini
32de0 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a tialized in a.**
32df0 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 way that makes
32e00 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b it safe to invok
32e10 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
32e20 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 close()] on *ppB
32e30 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 lob.** regardles
32e40 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 s of the success
32e50 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 or failure of t
32e60 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a his routine..**.
32e70 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f 77 20 ** ^(If the row
32e80 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 that a BLOB hand
32e90 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 le points to is
32ea0 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a modified by an.*
32eb0 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c * [UPDATE], [DEL
32ec0 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 ETE], or by [ON
32ed0 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 CONFLICT] side-e
32ee0 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 ffects.** then t
32ef0 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 he BLOB handle i
32f00 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 s marked as "exp
32f10 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 ired"..** This i
32f20 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f s true if any co
32f30 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 lumn of the row
32f40 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e is changed, even
32f50 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 a column.** oth
32f60 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 er than the one
32f70 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 the BLOB handle
32f80 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a is open on.)^.**
32f90 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 ^Calls to [sqli
32fa0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d te3_blob_read()]
32fb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c and [sqlite3_bl
32fc0 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a ob_write()] for.
32fd0 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f ** a expired BLO
32fe0 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 B handle fail wi
32ff0 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 th an return cod
33000 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f e of [SQLITE_ABO
33010 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 RT]..** ^(Change
33020 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 s written into a
33030 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 BLOB prior to t
33040 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 he BLOB expiring
33050 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c are not.** roll
33060 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 back by the expi
33070 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c ration of the BL
33080 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 OB. Such change
33090 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c s will eventuall
330a0 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 y.** commit if t
330b0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 he transaction c
330c0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 ontinues to comp
330d0 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 letion.)^.**.**
330e0 5e 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 ^Use the [sqlite
330f0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 3_blob_bytes()]
33100 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74 interface to det
33110 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20 ermine the size
33120 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 of.** the opened
33130 20 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69 7a blob. ^The siz
33140 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 e of a blob may
33150 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 not be changed b
33160 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 y this.** interf
33170 61 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 ace. Use the [U
33180 50 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 PDATE] SQL comma
33190 6e 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 nd to change the
331a0 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c size of a.** bl
331b0 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b ob..**.** ^The [
331c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
331d0 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 oblob()] and [sq
331e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
331f0 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 oblob()] interfa
33200 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 ces.** and the b
33210 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f uilt-in [zeroblo
33220 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 b] SQL function
33230 63 61 6e 20 62 65 20 75 73 65 64 2c 20 69 66 20 can be used, if
33240 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 desired,.** to c
33250 72 65 61 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 reate an empty,
33260 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 zero-filled blob
33270 20 69 6e 20 77 68 69 63 68 20 74 6f 20 72 65 61 in which to rea
33280 64 20 6f 72 20 77 72 69 74 65 20 75 73 69 6e 67 d or write using
33290 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 .** this interfa
332a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f ce..**.** To avo
332b0 69 64 20 61 20 72 65 73 6f 75 72 63 65 20 6c 65 id a resource le
332c0 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e 20 5b ak, every open [
332d0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f BLOB handle] sho
332e0 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a uld eventually.*
332f0 2a 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 * be released by
33300 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
33310 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 te3_blob_close()
33320 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
33330 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 3_blob_open(. s
33340 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 qlite3*,. const
33350 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f char *zDb,. co
33360 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 nst char *zTable
33370 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
33380 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 zColumn,. sqlit
33390 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 e3_int64 iRow,.
333a0 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 int flags,. sq
333b0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 lite3_blob **ppB
333c0 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lob.);../*.** CA
333d0 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 PI3REF: Close A
333e0 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a BLOB Handle.**.*
333f0 2a 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 * ^Closes an ope
33400 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e n [BLOB handle].
33410 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 .**.** ^Closing
33420 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 a BLOB shall cau
33430 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 se the current t
33440 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f ransaction to co
33450 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 mmit.** if there
33460 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c are no other BL
33470 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 OBs, no pending
33480 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
33490 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 nts, and the.**
334a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
334b0 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 ion is in [autoc
334c0 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 ommit mode]..**
334d0 5e 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 ^If any writes w
334e0 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 ere made to the
334f0 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 BLOB, they might
33500 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 be held in cach
33510 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 e.** until the c
33520 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 lose operation i
33530 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e f they will fit.
33540 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 .**.** ^(Closing
33550 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 the BLOB often
33560 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 forces the chang
33570 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 es.** out to dis
33580 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 k and so if any
33590 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 I/O errors occur
335a0 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 , they will like
335b0 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 ly occur.** at t
335c0 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 he time when the
335d0 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e BLOB is closed.
335e0 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 Any errors tha
335f0 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a t occur during.*
33600 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 * closing are re
33610 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d ported as a non-
33620 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 zero return valu
33630 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 e.)^.**.** ^(The
33640 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 BLOB is closed
33650 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e unconditionally.
33660 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 Even if this r
33670 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a outine returns.*
33680 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c * an error code,
33690 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 the BLOB is sti
336a0 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a ll closed.)^.**.
336b0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 ** ^Calling this
336c0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 routine with a
336d0 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73 75 null pointer (su
336e0 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 ch as would be r
336f0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20 eturned.** by a
33700 66 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b failed call to [
33710 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
33720 6e 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c n()]) is a harml
33730 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e ess no-op..*/.in
33740 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 t sqlite3_blob_c
33750 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f lose(sqlite3_blo
33760 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 b *);../*.** CAP
33770 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 I3REF: Return Th
33780 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 e Size Of An Ope
33790 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 n BLOB.**.** ^Re
337a0 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 turns the size i
337b0 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 n bytes of the B
337c0 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 LOB accessible v
337d0 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 ia the .** succe
337e0 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b ssfully opened [
337f0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 BLOB handle] in
33800 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e its only argumen
33810 74 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 t. ^The.** incr
33820 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f emental blob I/O
33830 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e routines can on
33840 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 ly read or overw
33850 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a riting existing.
33860 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b ** blob content;
33870 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 they cannot cha
33880 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 nge the size of
33890 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 a blob..**.** Th
338a0 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 is routine only
338b0 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 works on a [BLOB
338c0 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 handle] which h
338d0 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a as been created.
338e0 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 ** by a prior su
338f0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
33900 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
33910 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 pen()] and which
33920 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e has not.** been
33930 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 closed by [sqli
33940 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 te3_blob_close()
33950 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 ]. Passing any
33960 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e other pointer in
33970 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 .** to this rout
33980 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 ine results in u
33990 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
339a0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c bably undesirabl
339b0 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 e behavior..*/.i
339c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
339d0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c bytes(sqlite3_bl
339e0 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ob *);../*.** CA
339f0 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 PI3REF: Read Dat
33a00 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e a From A BLOB In
33a10 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a crementally.**.*
33a20 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f * ^(This functio
33a30 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 n is used to rea
33a40 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f d data from an o
33a50 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 pen [BLOB handle
33a60 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c ] into a.** call
33a70 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 er-supplied buff
33a80 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 er. N bytes of d
33a90 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 ata are copied i
33aa0 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 nto buffer Z.**
33ab0 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c from the open BL
33ac0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 OB, starting at
33ad0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 29 offset iOffset.)
33ae0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 ^.**.** ^If offs
33af0 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 et iOffset is le
33b00 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 ss than N bytes
33b10 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 from the end of
33b20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 the BLOB,.** [SQ
33b30 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 LITE_ERROR] is r
33b40 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 eturned and no d
33b50 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e 49 ata is read. ^I
33b60 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 f N or iOffset i
33b70 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a s.** less than z
33b80 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 ero, [SQLITE_ERR
33b90 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 OR] is returned
33ba0 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 and no data is r
33bb0 65 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 7a ead..** ^The siz
33bc0 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28 61 e of the blob (a
33bd0 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 nd hence the max
33be0 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b imum value of N+
33bf0 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 iOffset).** can
33c00 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 be determined us
33c10 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ing the [sqlite3
33c20 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 _blob_bytes()] i
33c30 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
33c40 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 ^An attempt to r
33c50 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69 ead from an expi
33c60 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 red [BLOB handle
33c70 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a ] fails with an.
33c80 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 ** error code of
33c90 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e [SQLITE_ABORT].
33ca0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 .**.** ^(On succ
33cb0 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f ess, sqlite3_blo
33cc0 62 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e 73 b_read() returns
33cd0 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f SQLITE_OK..** O
33ce0 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 therwise, an [er
33cf0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 ror code] or an
33d00 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
33d10 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
33d20 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 d.)^.**.** This
33d30 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 routine only wor
33d40 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 ks on a [BLOB ha
33d50 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 ndle] which has
33d60 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 been created.**
33d70 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 by a prior succe
33d80 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
33d90 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
33da0 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 ()] and which ha
33db0 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c s not.** been cl
33dc0 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 osed by [sqlite3
33dd0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 _blob_close()].
33de0 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 Passing any oth
33df0 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a er pointer in.**
33e00 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
33e10 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 results in unde
33e20 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
33e30 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 ly undesirable b
33e40 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 ehavior..**.** S
33e50 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
33e60 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e 3_blob_write()].
33e70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
33e80 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 blob_read(sqlite
33e90 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 3_blob *, void *
33ea0 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f Z, int N, int iO
33eb0 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ffset);../*.** C
33ec0 41 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 API3REF: Write D
33ed0 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 ata Into A BLOB
33ee0 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a Incrementally.**
33ef0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
33f00 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 on is used to wr
33f10 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e ite data into an
33f20 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 open [BLOB hand
33f30 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 le] from a.** ca
33f40 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 ller-supplied bu
33f50 66 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20 6f ffer. ^N bytes o
33f60 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 f data are copie
33f70 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 d from the buffe
33f80 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 r Z.** into the
33f90 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 open BLOB, start
33fa0 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f ing at offset iO
33fb0 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 ffset..**.** ^If
33fc0 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c the [BLOB handl
33fd0 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 e] passed as the
33fe0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
33ff0 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 was not opened f
34000 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 or.** writing (t
34010 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
34020 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
34030 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 lob_open()] was
34040 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 zero),.** this f
34050 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
34060 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 [SQLITE_READONLY
34070 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 ]..**.** ^This f
34080 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 unction may only
34090 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 modify the cont
340a0 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 ents of the BLOB
340b0 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 ; it is.** not p
340c0 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 ossible to incre
340d0 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ase the size of
340e0 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 a BLOB using thi
340f0 73 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66 s API..** ^If of
34100 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 fset iOffset is
34110 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 less than N byte
34120 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f s from the end o
34130 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b f the BLOB,.** [
34140 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 SQLITE_ERROR] is
34150 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f returned and no
34160 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e data is written
34170 2e 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 6c . ^If N is.** l
34180 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 ess than zero [S
34190 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 QLITE_ERROR] is
341a0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 returned and no
341b0 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e data is written.
341c0 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 .** The size of
341d0 74 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 the BLOB (and he
341e0 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 nce the maximum
341f0 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 value of N+iOffs
34200 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 et).** can be de
34210 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 termined using t
34220 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
34230 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
34240 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 ace..**.** ^An a
34250 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 ttempt to write
34260 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 to an expired [B
34270 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c LOB handle] fail
34280 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 s with an.** err
34290 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 or code of [SQLI
342a0 54 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72 69 TE_ABORT]. ^Wri
342b0 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 tes to the BLOB
342c0 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a that occurred.**
342d0 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f before the [BLO
342e0 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 B handle] expire
342f0 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 d are not rolled
34300 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 back by the.**
34310 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 expiration of th
34320 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 e handle, though
34330 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 of course those
34340 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a changes might.*
34350 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 * have been over
34360 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 written by the s
34370 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 tatement that ex
34380 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68 pired the BLOB h
34390 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f andle.** or by o
343a0 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 ther independent
343b0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
343c0 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c ** ^(On success,
343d0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 sqlite3_blob_wr
343e0 69 74 65 28 29 20 72 65 74 75 72 6e 73 20 53 51 ite() returns SQ
343f0 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 LITE_OK..** Othe
34400 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f rwise, an [erro
34410 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 r code] or an [e
34420 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
34430 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
34440 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f )^.**.** This ro
34450 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 utine only works
34460 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 on a [BLOB hand
34470 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 le] which has be
34480 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 en created.** by
34490 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 a prior success
344a0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
344b0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 ite3_blob_open()
344c0 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 ] and which has
344d0 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 not.** been clos
344e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 ed by [sqlite3_b
344f0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 lob_close()]. P
34500 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 assing any other
34510 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 pointer in.** t
34520 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 o this routine r
34530 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 esults in undefi
34540 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 ned and probably
34550 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 undesirable beh
34560 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 avior..**.** See
34570 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
34580 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f blob_read()]..*/
34590 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f .int sqlite3_blo
345a0 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f b_write(sqlite3_
345b0 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f blob *, const vo
345c0 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e id *z, int n, in
345d0 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a t iOffset);../*.
345e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
345f0 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d tual File System
34600 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 Objects.**.** A
34610 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 virtual filesys
34620 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 tem (VFS) is an
34630 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
34640 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c ject.** that SQL
34650 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 ite uses to inte
34660 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 ract.** with the
34670 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
34680 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d ating system. M
34690 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64 ost SQLite build
346a0 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a s come with a.**
346b0 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 single default
346c0 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72 VFS that is appr
346d0 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 opriate for the
346e0 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a host computer..*
346f0 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 * New VFSes can
34700 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e be registered an
34710 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 d existing VFSes
34720 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 can be unregist
34730 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c ered..** The fol
34740 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 lowing interface
34750 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a s are provided..
34760 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
34770 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e e3_vfs_find() in
34780 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
34790 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 a pointer to a V
347a0 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d FS given its nam
347b0 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 e..** ^Names are
347c0 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e case sensitive.
347d0 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 7a .** ^Names are z
347e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
347f0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a TF-8 strings..**
34800 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f ^If there is no
34810 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 match, a NULL p
34820 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
34830 65 64 2e 0a 2a 2a 20 5e 49 66 20 7a 56 66 73 4e ed..** ^If zVfsN
34840 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e ame is NULL then
34850 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 the default VFS
34860 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
34870 0a 2a 2a 20 5e 4e 65 77 20 56 46 53 65 73 20 61 .** ^New VFSes a
34880 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 re registered wi
34890 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 th sqlite3_vfs_r
348a0 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 5e 45 egister()..** ^E
348b0 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f ach new VFS beco
348c0 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 mes the default
348d0 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 VFS if the makeD
348e0 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e flt flag is set.
348f0 0a 2a 2a 20 5e 54 68 65 20 73 61 6d 65 20 56 46 .** ^The same VF
34900 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 S can be registe
34910 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d red multiple tim
34920 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 es without injur
34930 79 2e 0a 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20 61 y..** ^To make a
34940 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69 n existing VFS i
34950 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 nto the default
34960 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74 VFS, register it
34970 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 again.** with t
34980 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 he makeDflt flag
34990 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69 set. If two di
349a0 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 fferent VFSes wi
349b0 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e th the.** same n
349c0 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72 ame are register
349d0 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 ed, the behavior
349e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 is undefined.
349f0 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 If a.** VFS is r
34a00 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61 egistered with a
34a10 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 name that is NU
34a20 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 LL or an empty s
34a30 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 tring,.** then t
34a40 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
34a50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
34a60 5e 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 ^Unregister a VF
34a70 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 S with the sqlit
34a80 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 e3_vfs_unregiste
34a90 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a r() interface..*
34aa0 2a 20 5e 28 49 66 20 74 68 65 20 64 65 66 61 75 * ^(If the defau
34ab0 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 lt VFS is unregi
34ac0 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 stered, another
34ad0 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 VFS is chosen as
34ae0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e .** the default.
34af0 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 The choice for
34b00 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 the new VFS is
34b10 61 72 62 69 74 72 61 72 79 2e 29 5e 0a 2a 2f 0a arbitrary.)^.*/.
34b20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c sqlite3_vfs *sql
34b30 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f ite3_vfs_find(co
34b40 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 nst char *zVfsNa
34b50 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 me);.int sqlite3
34b60 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 _vfs_register(sq
34b70 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
34b80 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 makeDflt);.int s
34b90 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 qlite3_vfs_unreg
34ba0 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 ister(sqlite3_vf
34bb0 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 s*);../*.** CAPI
34bc0 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 3REF: Mutexes.**
34bd0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
34be0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72 ore uses these r
34bf0 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 outines for thre
34c00 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a ad.** synchroniz
34c10 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 ation. Though th
34c20 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 ey are intended
34c30 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 for internal.**
34c40 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 use by SQLite, c
34c50 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 ode that links a
34c60 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 gainst SQLite is
34c70 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f .** permitted to
34c80 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 use any of thes
34c90 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a e routines..**.*
34ca0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 * The SQLite sou
34cb0 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e rce code contain
34cc0 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 s multiple imple
34cd0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 mentations.** of
34ce0 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 these mutex rou
34cf0 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f tines. An appro
34d00 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 priate implement
34d10 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 ation.** is sele
34d20 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c cted automatical
34d30 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 ly at compile-ti
34d40 6d 65 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f me. ^(The follo
34d50 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e wing.** implemen
34d60 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 tations are avai
34d70 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c lable in the SQL
34d80 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 ite core:.**.**
34d90 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 <ul>.** <li> S
34da0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a QLITE_MUTEX_OS2.
34db0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 ** <li> SQLITE
34dc0 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a _MUTEX_PTHREAD.*
34dd0 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f * <li> SQLITE_
34de0 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 MUTEX_W32.** <li
34df0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 > SQLITE_MUTEX
34e00 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e _NOOP.** </ul>)^
34e10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 .**.** ^The SQLI
34e20 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d TE_MUTEX_NOOP im
34e30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
34e40 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 a set of routine
34e50 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e s.** that does n
34e60 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 o real locking a
34e70 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 nd is appropriat
34e80 65 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 e for use in.**
34e90 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 a single-threade
34ea0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 d application.
34eb0 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 ^The SQLITE_MUTE
34ec0 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 X_OS2,.** SQLITE
34ed0 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20 _MUTEX_PTHREAD,
34ee0 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 and SQLITE_MUTEX
34ef0 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 _W32 implementat
34f00 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 ions.** are appr
34f10 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 opriate for use
34f20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 on OS/2, Unix, a
34f30 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a nd Windows..**.*
34f40 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 69 73 * ^(If SQLite is
34f50 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
34f60 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f he SQLITE_MUTEX_
34f70 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73 APPDEF preproces
34f80 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 sor.** macro def
34f90 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51 ined (with "-DSQ
34fa0 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 LITE_MUTEX_APPDE
34fb0 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d F=1"), then no m
34fc0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e utex.** implemen
34fd0 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 tation is includ
34fe0 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 ed with the libr
34ff0 61 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61 73 ary. In this cas
35000 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 e the.** applica
35010 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 tion must supply
35020 20 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 a custom mutex
35030 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 implementation u
35040 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c sing the.** [SQL
35050 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
35060 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 ] option of the
35070 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
35080 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 function.** bef
35090 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 ore calling sqli
350a0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
350b0 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70 75 or any other pu
350c0 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a blic sqlite3_.**
350d0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 function that c
350e0 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 alls sqlite3_ini
350f0 74 69 61 6c 69 7a 65 28 29 2e 29 5e 0a 2a 2a 0a tialize().)^.**.
35100 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
35110 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f mutex_alloc() ro
35120 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 utine allocates
35130 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 a new.** mutex a
35140 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 nd returns a poi
35150 6e 74 65 72 20 74 6f 20 69 74 2e 20 5e 49 66 20 nter to it. ^If
35160 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a it returns NULL.
35170 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ** that means th
35180 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 at a mutex could
35190 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 not be allocate
351a0 64 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 77 d. ^SQLite.** w
351b0 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 ill unwind its s
351c0 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 tack and return
351d0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 28 54 68 65 an error. ^(The
351e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
351f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
35200 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 loc() is one of
35210 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f these integer co
35220 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c nstants:.**.** <
35230 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c ul>.** <li> SQL
35240 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a ITE_MUTEX_FAST.*
35250 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
35260 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a UTEX_RECURSIVE.*
35270 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
35280 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 UTEX_STATIC_MAST
35290 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ER.** <li> SQLI
352a0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
352b0 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c MEM.** <li> SQL
352c0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
352d0 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 _MEM2.** <li> S
352e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
352f0 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 IC_PRNG.** <li>
35300 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
35310 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e ATIC_LRU.** <li>
35320 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
35330 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f TATIC_LRU2.** </
35340 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ul>)^.**.** ^The
35350 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 first two const
35360 61 6e 74 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 ants (SQLITE_MUT
35370 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49 EX_FAST and SQLI
35380 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
35390 56 45 29 0a 2a 2a 20 63 61 75 73 65 20 73 71 6c VE).** cause sql
353a0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
353b0 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 () to create.**
353c0 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 5e 54 a new mutex. ^T
353d0 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20 he new mutex is
353e0 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53 recursive when S
353f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
35400 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 RSIVE.** is used
35410 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 but not necessa
35420 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c rily so when SQL
35430 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 ITE_MUTEX_FAST i
35440 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d s used..** The m
35450 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 utex implementat
35460 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ion does not nee
35470 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 d to make a dist
35480 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 inction.** betwe
35490 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f en SQLITE_MUTEX_
354a0 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51 RECURSIVE and SQ
354b0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 LITE_MUTEX_FAST
354c0 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f if it does.** no
354d0 74 20 77 61 6e 74 20 74 6f 2e 20 20 5e 53 51 4c t want to. ^SQL
354e0 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 ite will only re
354f0 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69 76 quest a recursiv
35500 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 e mutex in.** ca
35510 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65 61 ses where it rea
35520 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 lly needs one.
35530 5e 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e ^If a faster non
35540 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 -recursive mutex
35550 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
35560 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 on is available
35570 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 on the host plat
35580 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 form, the mutex
35590 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 subsystem.** mig
355a0 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 ht return such a
355b0 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e mutex in respon
355c0 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 se to SQLITE_MUT
355d0 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e EX_FAST..**.** ^
355e0 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 The other allowe
355f0 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 d parameters to
35600 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
35610 6c 6f 63 28 29 20 28 61 6e 79 74 68 69 6e 67 20 loc() (anything
35620 6f 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 53 51 other.** than SQ
35630 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 LITE_MUTEX_FAST
35640 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 and SQLITE_MUTEX
35650 5f 52 45 43 55 52 53 49 56 45 29 20 65 61 63 68 _RECURSIVE) each
35660 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 return.** a poi
35670 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 nter to a static
35680 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 preexisting mut
35690 65 78 2e 20 20 5e 53 69 78 20 73 74 61 74 69 63 ex. ^Six static
356a0 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 mutexes are.**
356b0 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72 used by the curr
356c0 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 ent version of S
356d0 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 QLite. Future v
356e0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
356f0 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 e.** may add add
35700 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d itional static m
35710 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 utexes. Static
35720 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 mutexes are for
35730 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 internal.** use
35740 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 by SQLite only.
35750 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
35760 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 at use SQLite mu
35770 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 texes should.**
35780 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e use only the dyn
35790 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 amic mutexes ret
357a0 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f urned by SQLITE_
357b0 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a MUTEX_FAST or.**
357c0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 SQLITE_MUTEX_RE
357d0 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e CURSIVE..**.** ^
357e0 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 Note that if one
357f0 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 of the dynamic
35800 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 mutex parameters
35810 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 (SQLITE_MUTEX_F
35820 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 AST.** or SQLITE
35830 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 _MUTEX_RECURSIVE
35840 29 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 ) is used then s
35850 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
35860 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 oc().** returns
35870 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 a different mute
35880 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e x on every call.
35890 20 20 5e 42 75 74 20 66 6f 72 20 74 68 65 20 73 ^But for the s
358a0 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 tatic.** mutex t
358b0 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d ypes, the same m
358c0 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64 utex is returned
358d0 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74 on every call t
358e0 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 hat has.** the s
358f0 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e ame type number.
35900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
35910 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 te3_mutex_free()
35920 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 routine dealloc
35930 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c ates a previousl
35940 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 y.** allocated d
35950 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 20 5e ynamic mutex. ^
35960 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 SQLite is carefu
35970 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 l to deallocate
35980 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 every.** dynamic
35990 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61 mutex that it a
359a0 6c 6c 6f 63 61 74 65 73 2e 20 20 54 68 65 20 64 llocates. The d
359b0 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d ynamic mutexes m
359c0 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a ust not be in.**
359d0 20 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61 use when they a
359e0 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 re deallocated.
359f0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 Attempting to d
35a00 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74 eallocate a stat
35a10 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 ic.** mutex resu
35a20 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 lts in undefined
35a30 20 62 65 68 61 76 69 6f 72 2e 20 20 5e 53 51 4c behavior. ^SQL
35a40 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f ite never deallo
35a50 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 cates.** a stati
35a60 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e c mutex..**.** ^
35a70 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
35a80 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 x_enter() and sq
35a90 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
35aa0 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d ) routines attem
35ab0 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 pt.** to enter a
35ac0 20 6d 75 74 65 78 2e 20 20 5e 49 66 20 61 6e 6f mutex. ^If ano
35ad0 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61 ther thread is a
35ae0 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 lready within th
35af0 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 e mutex,.** sqli
35b00 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 te3_mutex_enter(
35b10 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 ) will block and
35b20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
35b30 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e ry() will return
35b40 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e .** SQLITE_BUSY.
35b50 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d ^The sqlite3_m
35b60 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 utex_try() inter
35b70 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 face returns [SQ
35b80 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e LITE_OK].** upon
35b90 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 successful entr
35ba0 79 2e 20 20 5e 28 4d 75 74 65 78 65 73 20 63 72 y. ^(Mutexes cr
35bb0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 eated using.** S
35bc0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
35bd0 52 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74 RSIVE can be ent
35be0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 ered multiple ti
35bf0 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20 mes by the same
35c00 74 68 72 65 61 64 2e 0a 2a 2a 20 49 6e 20 73 75 thread..** In su
35c10 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a ch cases the,.**
35c20 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 mutex must be e
35c30 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e xited an equal n
35c40 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 umber of times b
35c50 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 efore another th
35c60 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 read.** can ente
35c70 72 2e 29 5e 20 20 5e 28 49 66 20 74 68 65 20 73 r.)^ ^(If the s
35c80 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73 ame thread tries
35c90 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 to enter any ot
35ca0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d her.** kind of m
35cb0 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f utex more than o
35cc0 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f nce, the behavio
35cd0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
35ce0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e ** SQLite will n
35cf0 65 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 ever exhibit.**
35d00 73 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e such behavior in
35d10 20 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 its own use of
35d20 6d 75 74 65 78 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a mutexes.)^.**.**
35d30 20 5e 28 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 ^(Some systems
35d40 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 (for example, Wi
35d50 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 ndows 95) do not
35d60 20 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65 support the ope
35d70 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d ration.** implem
35d80 65 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 ented by sqlite3
35d90 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f _mutex_try(). O
35da0 6e 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c n those systems,
35db0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
35dc0 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 ry().** will alw
35dd0 61 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 ays return SQLIT
35de0 45 5f 42 55 53 59 2e 20 20 54 68 65 20 53 51 4c E_BUSY. The SQL
35df0 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 ite core only ev
35e00 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 er uses.** sqlit
35e10 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 e3_mutex_try() a
35e20 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f s an optimizatio
35e30 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 n so this is acc
35e40 65 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 eptable behavior
35e50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
35e60 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 qlite3_mutex_lea
35e70 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 ve() routine exi
35e80 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 ts a mutex that
35e90 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c was.** previousl
35ea0 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 y entered by the
35eb0 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 20 same thread.
35ec0 5e 28 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a ^(The behavior.*
35ed0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 * is undefined i
35ee0 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e f the mutex is n
35ef0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ot currently ent
35f00 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 ered by the.** c
35f10 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 alling thread or
35f20 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
35f30 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 y allocated. SQ
35f40 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 Lite will.** nev
35f50 65 72 20 64 6f 20 65 69 74 68 65 72 2e 29 5e 0a er do either.)^.
35f60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 **.** ^If the ar
35f70 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
35f80 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 2c 3_mutex_enter(),
35f90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
35fa0 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 ry(), or.** sqli
35fb0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 te3_mutex_leave(
35fc0 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ) is a NULL poin
35fd0 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68 ter, then all th
35fe0 72 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ree routines.**
35ff0 62 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73 behave as no-ops
36000 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
36010 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 : [sqlite3_mutex
36020 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 _held()] and [sq
36030 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 lite3_mutex_noth
36040 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 eld()]..*/.sqlit
36050 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 e3_mutex *sqlite
36060 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 3_mutex_alloc(in
36070 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
36080 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69 _mutex_free(sqli
36090 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 te3_mutex*);.voi
360a0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
360b0 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 enter(sqlite3_mu
360c0 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 tex*);.int sqlit
360d0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c e3_mutex_try(sql
360e0 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f ite3_mutex*);.vo
360f0 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 id sqlite3_mutex
36100 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d _leave(sqlite3_m
36110 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 utex*);../*.** C
36120 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 4d API3REF: Mutex M
36130 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a ethods Object.**
36140 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
36150 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
36160 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
36170 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c 6f e defines the lo
36180 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 w-level routines
36190 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f .** used to allo
361a0 63 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75 74 cate and use mut
361b0 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 exes..**.** Usua
361c0 6c 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c 74 lly, the default
361d0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 mutex implement
361e0 61 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 ations provided
361f0 62 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a by SQLite are.**
36200 20 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 sufficient, how
36210 65 76 65 72 20 74 68 65 20 75 73 65 72 20 68 61 ever the user ha
36220 73 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 s the option of
36230 73 75 62 73 74 69 74 75 74 69 6e 67 20 61 20 63 substituting a c
36240 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ustom.** impleme
36250 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 ntation for spec
36260 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 ialized deployme
36270 6e 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20 66 nts or systems f
36280 6f 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 0a or which SQLite.
36290 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 ** does not prov
362a0 69 64 65 20 61 20 73 75 69 74 61 62 6c 65 20 69 ide a suitable i
362b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 mplementation. I
362c0 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 n this case, the
362d0 20 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 user.** creates
362e0 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 61 and populates a
362f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
36300 69 73 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 is structure to
36310 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 pass.** to sqlit
36320 65 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e e3_config() alon
36330 67 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 g with the [SQLI
36340 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d TE_CONFIG_MUTEX]
36350 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 option..** Addi
36360 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 tionally, an ins
36370 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 tance of this st
36380 72 75 63 74 75 72 65 20 63 61 6e 20 62 65 20 75 ructure can be u
36390 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 sed as an.** out
363a0 70 75 74 20 76 61 72 69 61 62 6c 65 20 77 68 65 put variable whe
363b0 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 73 n querying the s
363c0 79 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63 75 ystem for the cu
363d0 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 rrent mutex.** i
363e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 mplementation, u
363f0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
36400 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
36410 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ] option..**.**
36420 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 ^The xMutexInit
36430 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 method defined b
36440 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 y this structure
36450 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a is invoked as.*
36460 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d * part of system
36470 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
36480 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 by the sqlite3_i
36490 6e 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 nitialize() func
364a0 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 20 78 4d tion..** ^The xM
364b0 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 utexInit routine
364c0 20 69 73 20 63 61 6c 6c 65 20 62 79 20 53 51 4c is calle by SQL
364d0 69 74 65 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 ite exactly once
364e0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 for each.** eff
364f0 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b ective call to [
36500 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
36510 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ze()]..**.** ^Th
36520 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 e xMutexEnd meth
36530 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 od defined by th
36540 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 is structure is
36550 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 invoked as.** pa
36560 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 rt of system shu
36570 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c tdown by the sql
36580 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
36590 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a function. The.**
365a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
365b0 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 of this method i
365c0 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 72 65 s expected to re
365d0 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 lease all outsta
365e0 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 nding.** resourc
365f0 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 es obtained by t
36600 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 he mutex methods
36610 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c implementation,
36620 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 especially.** t
36630 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79 hose obtained by
36640 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 the xMutexInit
36650 6d 65 74 68 6f 64 2e 20 20 5e 54 68 65 20 78 4d method. ^The xM
36660 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 utexEnd().** int
36670 65 72 66 61 63 65 20 69 73 20 69 6e 76 6f 6b 65 erface is invoke
36680 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 d exactly once f
36690 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 or each call to
366a0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
366b0 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 n()]..**.** ^(Th
366c0 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 e remaining seve
366d0 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 n methods define
366e0 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 d by this struct
366f0 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 ure (xMutexAlloc
36700 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c ,.** xMutexFree,
36710 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d xMutexEnter, xM
36720 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c utexTry, xMutexL
36730 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 eave, xMutexHeld
36740 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f and.** xMutexNo
36750 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 theld) implement
36760 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 the following i
36770 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 70 65 nterfaces (respe
36780 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 ctively):.**.**
36790 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 <ul>.** <li>
367a0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 [sqlite3_mutex_a
367b0 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a lloc()] </li>.**
367c0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 <li> [sqlite
367d0 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3_mutex_free()]
367e0 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 </li>.** <li>
367f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
36800 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a enter()] </li>.*
36810 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 * <li> [sqlit
36820 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 e3_mutex_try()]
36830 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 </li>.** <li>
36840 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
36850 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a leave()] </li>.*
36860 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 * <li> [sqlit
36870 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d e3_mutex_held()]
36880 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e </li>.** <li>
36890 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 [sqlite3_mutex
368a0 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 _notheld()] </li
368b0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a >.** </ul>)^.**.
368c0 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 ** The only diff
368d0 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 erence is that t
368e0 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 he public sqlite
368f0 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 3_XXX functions
36900 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 enumerated.** ab
36910 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e ove silently ign
36920 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 ore any invocati
36930 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 20 ons that pass a
36940 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 NULL pointer ins
36950 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c tead.** of a val
36960 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e id mutex handle.
36970 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
36980 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 ions of the meth
36990 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 ods defined.** b
369a0 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 y this structure
369b0 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 are not require
369c0 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 d to handle this
369d0 20 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c case, the resul
369e0 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 ts.** of passing
369f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
36a00 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c instead of a val
36a10 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 id mutex handle
36a20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a are undefined.**
36a30 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 (i.e. it is acc
36a40 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 eptable to provi
36a50 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 de an implementa
36a60 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 tion that segfau
36a70 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 lts if.** it is
36a80 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f passed a NULL po
36a90 69 6e 74 65 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 inter)..**.** Th
36aa0 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d e xMutexInit() m
36ab0 65 74 68 6f 64 20 6d 75 73 74 20 62 65 20 74 68 ethod must be th
36ac0 72 65 61 64 73 61 66 65 2e 20 20 5e 49 74 20 6d readsafe. ^It m
36ad0 75 73 74 20 62 65 20 68 61 72 6d 6c 65 73 73 20 ust be harmless
36ae0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 78 4d 75 to.** invoke xMu
36af0 74 65 78 49 6e 69 74 28 29 20 6d 75 74 69 70 6c texInit() mutipl
36b00 65 20 74 69 6d 65 73 20 77 69 74 68 69 6e 20 74 e times within t
36b10 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 20 he same process
36b20 61 6e 64 20 77 69 74 68 6f 75 74 0a 2a 2a 20 69 and without.** i
36b30 6e 74 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c 73 ntervening calls
36b40 20 74 6f 20 78 4d 75 74 65 78 45 6e 64 28 29 2e to xMutexEnd().
36b50 20 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 Second and sub
36b60 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
36b70 0a 2a 2a 20 78 4d 75 74 65 78 49 6e 69 74 28 29 .** xMutexInit()
36b80 20 6d 75 73 74 20 62 65 20 6e 6f 2d 6f 70 73 2e must be no-ops.
36b90 0a 2a 2a 0a 2a 2a 20 5e 78 4d 75 74 65 78 49 6e .**.** ^xMutexIn
36ba0 69 74 28 29 20 6d 75 73 74 20 6e 6f 74 20 75 73 it() must not us
36bb0 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 e SQLite memory
36bc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 5b 73 71 6c allocation ([sql
36bd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a ite3_malloc()].*
36be0 2a 20 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69 * and its associ
36bf0 61 74 65 73 29 2e 20 20 5e 53 69 6d 69 6c 61 72 ates). ^Similar
36c00 6c 79 2c 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 ly, xMutexAlloc(
36c10 29 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 ) must not use S
36c20 51 4c 69 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 QLite memory.**
36c30 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 allocation for a
36c40 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 20 static mutex.
36c50 5e 48 6f 77 65 76 65 72 20 78 4d 75 74 65 78 41 ^However xMutexA
36c60 6c 6c 6f 63 28 29 20 6d 61 79 20 75 73 65 20 53 lloc() may use S
36c70 51 4c 69 74 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 QLite.** memory
36c80 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 allocation for a
36c90 20 66 61 73 74 20 6f 72 20 72 65 63 75 72 73 69 fast or recursi
36ca0 76 65 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 ve mutex..**.**
36cb0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 ^SQLite will inv
36cc0 6f 6b 65 20 74 68 65 20 78 4d 75 74 65 78 45 6e oke the xMutexEn
36cd0 64 28 29 20 6d 65 74 68 6f 64 20 77 68 65 6e 20 d() method when
36ce0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
36cf0 6e 28 29 5d 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 n()] is.** calle
36d00 64 2c 20 62 75 74 20 6f 6e 6c 79 20 69 66 20 74 d, but only if t
36d10 68 65 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f he prior call to
36d20 20 78 4d 75 74 65 78 49 6e 69 74 20 72 65 74 75 xMutexInit retu
36d30 72 6e 65 64 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a rned SQLITE_OK..
36d40 2a 2a 20 49 66 20 78 4d 75 74 65 78 49 6e 69 74 ** If xMutexInit
36d50 20 66 61 69 6c 73 20 69 6e 20 61 6e 79 20 77 61 fails in any wa
36d60 79 2c 20 69 74 20 69 73 20 65 78 70 65 63 74 65 y, it is expecte
36d70 64 20 74 6f 20 63 6c 65 61 6e 20 75 70 20 61 66 d to clean up af
36d80 74 65 72 20 69 74 73 65 6c 66 0a 2a 2a 20 70 72 ter itself.** pr
36d90 69 6f 72 20 74 6f 20 72 65 74 75 72 6e 69 6e 67 ior to returning
36da0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
36db0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 uct sqlite3_mute
36dc0 78 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 x_methods sqlite
36dd0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b 3_mutex_methods;
36de0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
36df0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a mutex_methods {.
36e00 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e int (*xMutexIn
36e10 69 74 29 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74 it)(void);. int
36e20 20 28 2a 78 4d 75 74 65 78 45 6e 64 29 28 76 6f (*xMutexEnd)(vo
36e30 69 64 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d id);. sqlite3_m
36e40 75 74 65 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c utex *(*xMutexAl
36e50 6c 6f 63 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69 loc)(int);. voi
36e60 64 20 28 2a 78 4d 75 74 65 78 46 72 65 65 29 28 d (*xMutexFree)(
36e70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 sqlite3_mutex *)
36e80 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 ;. void (*xMute
36e90 78 45 6e 74 65 72 29 28 73 71 6c 69 74 65 33 5f xEnter)(sqlite3_
36ea0 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 mutex *);. int
36eb0 28 2a 78 4d 75 74 65 78 54 72 79 29 28 73 71 6c (*xMutexTry)(sql
36ec0 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 ite3_mutex *);.
36ed0 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 4c 65 void (*xMutexLe
36ee0 61 76 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 ave)(sqlite3_mut
36ef0 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ex *);. int (*x
36f00 4d 75 74 65 78 48 65 6c 64 29 28 73 71 6c 69 74 MutexHeld)(sqlit
36f10 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 e3_mutex *);. i
36f20 6e 74 20 28 2a 78 4d 75 74 65 78 4e 6f 74 68 65 nt (*xMutexNothe
36f30 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ld)(sqlite3_mute
36f40 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 x *);.};../*.**
36f50 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 CAPI3REF: Mutex
36f60 56 65 72 69 66 69 63 61 74 69 6f 6e 20 52 6f 75 Verification Rou
36f70 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tines.**.** The
36f80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
36f90 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ld() and sqlite3
36fa0 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 _mutex_notheld()
36fb0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 routines.** are
36fc0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
36fd0 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 e inside assert(
36fe0 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e ) statements. ^
36ff0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a The SQLite core.
37000 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74 68 ** never uses th
37010 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63 ese routines exc
37020 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73 ept inside an as
37030 73 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69 sert() and appli
37040 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 cations.** are a
37050 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 dvised to follow
37060 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65 the lead of the
37070 20 63 6f 72 65 2e 20 20 5e 54 68 65 20 53 51 4c core. ^The SQL
37080 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a ite core only.**
37090 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d provides implem
370a0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 entations for th
370b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65 ese routines whe
370c0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 n it is compiled
370d0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c .** with the SQL
370e0 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 ITE_DEBUG flag.
370f0 20 5e 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 ^External mutex
37100 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
37110 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 .** are only req
37120 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 uired to provide
37130 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
37140 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 if SQLITE_DEBUG
37150 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e is.** defined an
37160 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e d if NDEBUG is n
37170 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a ot defined..**.*
37180 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
37190 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 s should return
371a0 74 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 true if the mute
371b0 78 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d x in their argum
371c0 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f ent.** is held o
371d0 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 r not held, resp
371e0 65 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 ectively, by the
371f0 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e calling thread.
37200 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c .**.** ^The impl
37210 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f ementation is no
37220 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 t required to pr
37230 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 ovided versions
37240 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 of these.** rout
37250 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c ines that actual
37260 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 20 ly work. If the
37270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 implementation d
37280 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 oes not provide
37290 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 working.** versi
372a0 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ons of these rou
372b0 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 tines, it should
372c0 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64 at least provid
372d0 65 20 73 74 75 62 73 20 74 68 61 74 20 61 6c 77 e stubs that alw
372e0 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72 ays.** return tr
372f0 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 ue so that one d
37300 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72 oes not get spur
37310 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 66 ious assertion f
37320 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e ailures..**.** ^
37330 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 If the argument
37340 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 to sqlite3_mutex
37350 5f 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c _held() is a NUL
37360 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a L pointer then.*
37370 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 * the routine sh
37380 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 ould return 1.
37390 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e This seems coun
373a0 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 ter-intuitive si
373b0 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 nce.** clearly t
373c0 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 he mutex cannot
373d0 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f be held if it do
373e0 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 es not exist. B
373f0 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 ut the.** the re
37400 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 ason the mutex d
37410 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 oes not exist is
37420 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69 because the bui
37430 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 ld is not.** usi
37440 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 ng mutexes. And
37450 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 we do not want
37460 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e the assert() con
37470 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 taining the.** c
37480 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d all to sqlite3_m
37490 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 utex_held() to f
374a0 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 ail, so a non-ze
374b0 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 ro return is.**
374c0 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 the appropriate
374d0 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 5e 54 thing to do. ^T
374e0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
374f0 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a 2a 20 69 6e _notheld().** in
37500 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 61 terface should a
37510 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77 68 65 lso return 1 whe
37520 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 n given a NULL p
37530 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 ointer..*/.#ifnd
37540 65 66 20 4e 44 45 42 55 47 0a 69 6e 74 20 73 71 ef NDEBUG.int sq
37550 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 lite3_mutex_held
37560 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 (sqlite3_mutex*)
37570 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 ;.int sqlite3_mu
37580 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 tex_notheld(sqli
37590 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 23 65 6e te3_mutex*);.#en
375a0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
375b0 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 REF: Mutex Types
375c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
375d0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
375e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b )] interface tak
375f0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
37600 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 ment.** which is
37610 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e one of these in
37620 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e teger constants.
37630 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f .**.** The set o
37640 66 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 f static mutexes
37650 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d may change from
37660 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 6c 65 one SQLite rele
37670 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 ase to the.** ne
37680 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e xt. Application
37690 73 20 74 68 61 74 20 6f 76 65 72 72 69 64 65 20 s that override
376a0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74 the built-in mut
376b0 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 65 ex logic must be
376c0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74 6f 20 .** prepared to
376d0 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69 accommodate addi
376e0 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 tional static mu
376f0 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e texes..*/.#defin
37700 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 e SQLITE_MUTEX_F
37710 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 AST
37720 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
37730 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 _MUTEX_RECURSIVE
37740 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
37750 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 e SQLITE_MUTEX_S
37760 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20 TATIC_MASTER
37770 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
37780 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 _MUTEX_STATIC_ME
37790 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71 M 3 /* sq
377a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a lite3_malloc() *
377b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
377c0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 _MUTEX_STATIC_ME
377d0 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f M2 4 /* NO
377e0 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e T USED */.#defin
377f0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 e SQLITE_MUTEX_S
37800 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 20 20 20 TATIC_OPEN
37810 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 42 74 72 4 /* sqlite3Btr
37820 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66 eeOpen() */.#def
37830 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
37840 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20 _STATIC_PRNG
37850 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
37860 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 random() */.#def
37870 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
37880 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20 _STATIC_LRU
37890 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 6 /* lru page
378a0 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 list */.#define
378b0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
378c0 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20 20 37 ATIC_LRU2 7
378d0 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 /* lru page li
378e0 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 st */../*.** CAP
378f0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 65 20 I3REF: Retrieve
37900 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20 61 20 the mutex for a
37910 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
37920 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ion.**.** ^This
37930 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
37940 73 20 61 20 70 6f 69 6e 74 65 72 20 74 68 65 20 s a pointer the
37950 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
37960 6f 62 6a 65 63 74 20 74 68 61 74 20 0a 2a 2a 20 object that .**
37970 73 65 72 69 61 6c 69 7a 65 73 20 61 63 63 65 73 serializes acces
37980 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 s to the [databa
37990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 67 se connection] g
379a0 69 76 65 6e 20 69 6e 20 74 68 65 20 61 72 67 75 iven in the argu
379b0 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 74 68 65 ment.** when the
379c0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
379d0 5d 20 69 73 20 53 65 72 69 61 6c 69 7a 65 64 2e ] is Serialized.
379e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 74 68 72 .** ^If the [thr
379f0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 eading mode] is
37a00 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 6f 72 Single-thread or
37a10 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 74 68 Multi-thread th
37a20 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 en this.** routi
37a30 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c ne returns a NUL
37a40 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 L pointer..*/.sq
37a50 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c lite3_mutex *sql
37a60 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 73 71 ite3_db_mutex(sq
37a70 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
37a80 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 CAPI3REF: Low-Le
37a90 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 vel Control Of D
37aa0 61 74 61 62 61 73 65 20 46 69 6c 65 73 20 7b 48 atabase Files {H
37ab0 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 11300} <S30800>.
37ac0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
37ad0 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
37ae0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61 ()] interface ma
37af0 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61 6c kes a direct cal
37b00 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c l to the.** xFil
37b10 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
37b20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 for the [sqlite3
37b30 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
37b40 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a 2a ect associated.*
37b50 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 * with a particu
37b60 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64 65 lar database ide
37b70 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 ntified by the s
37b80 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 econd argument.
37b90 5e 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 ^The.** name of
37ba0 74 68 65 20 64 61 74 61 62 61 73 65 20 22 6d 61 the database "ma
37bb0 69 6e 22 20 66 6f 72 20 74 68 65 20 6d 61 69 6e in" for the main
37bc0 20 64 61 74 61 62 61 73 65 20 6f 72 20 22 74 65 database or "te
37bd0 6d 70 22 20 66 6f 72 20 74 68 65 0a 2a 2a 20 54 mp" for the.** T
37be0 45 4d 50 20 64 61 74 61 62 61 73 65 2c 20 6f 72 EMP database, or
37bf0 20 74 68 65 20 6e 61 6d 65 20 74 68 61 74 20 61 the name that a
37c00 70 70 65 61 72 73 20 61 66 74 65 72 20 74 68 65 ppears after the
37c10 20 41 53 20 6b 65 79 77 6f 72 64 20 66 6f 72 0a AS keyword for.
37c20 2a 2a 20 64 61 74 61 62 61 73 65 73 20 74 68 61 ** databases tha
37c30 74 20 61 72 65 20 61 64 64 65 64 20 75 73 69 6e t are added usin
37c40 67 20 74 68 65 20 5b 41 54 54 41 43 48 5d 20 53 g the [ATTACH] S
37c50 51 4c 20 63 6f 6d 6d 61 6e 64 2e 0a 2a 2a 20 5e QL command..** ^
37c60 41 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 63 A NULL pointer c
37c70 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c an be used in pl
37c80 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 20 74 6f ace of "main" to
37c90 20 72 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a refer to the.**
37ca0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 main database f
37cb0 69 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 ile..** ^The thi
37cc0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 rd and fourth pa
37cd0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 rameters to this
37ce0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65 20 routine.** are
37cf0 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79 20 passed directly
37d00 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 73 through to the s
37d10 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 econd and third
37d20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a 2a parameters of.**
37d30 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
37d40 6c 20 6d 65 74 68 6f 64 2e 20 20 5e 54 68 65 20 l method. ^The
37d50 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
37d60 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
37d70 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d .** method becom
37d80 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 es the return va
37d90 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 lue of this rout
37da0 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ine..**.** ^If t
37db0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
37dc0 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f ter (zDbName) do
37dd0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65 es not match the
37de0 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 name of any.**
37df0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 69 open database fi
37e00 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f le, then SQLITE_
37e10 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65 ERROR is returne
37e20 64 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 0a d. ^This error.
37e30 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 ** code is not r
37e40 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69 emembered and wi
37e50 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c ll not be recall
37e60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 ed by [sqlite3_e
37e70 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 rrcode()].** or
37e80 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
37e90 29 5d 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 )]. The underly
37ea0 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c ing xFileControl
37eb0 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a method might.**
37ec0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c also return SQL
37ed0 49 54 45 5f 45 52 52 4f 52 2e 20 20 54 68 65 72 ITE_ERROR. Ther
37ee0 65 20 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 e is no way to d
37ef0 69 73 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 istinguish betwe
37f00 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 en.** an incorre
37f10 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 ct zDbName and a
37f20 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 n SQLITE_ERROR r
37f30 65 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 eturn from the u
37f40 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 nderlying.** xFi
37f50 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
37f60 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
37f70 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f : [SQLITE_FCNTL_
37f80 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e LOCKSTATE].*/.in
37f90 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 t sqlite3_file_c
37fa0 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c ontrol(sqlite3*,
37fb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
37fc0 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f Name, int op, vo
37fd0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
37fe0 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 I3REF: Testing I
37ff0 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 5e nterface.**.** ^
38000 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65 73 74 The sqlite3_test
38010 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 65 72 _control() inter
38020 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
38030 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72 6e 61 read out interna
38040 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20 53 51 l.** state of SQ
38050 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e 6a 65 Lite and to inje
38060 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f 20 53 ct faults into S
38070 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74 69 6e QLite for testin
38080 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e 20 20 g.** purposes.
38090 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d ^The first param
380a0 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72 61 eter is an opera
380b0 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20 64 tion code that d
380c0 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 etermines.** the
380d0 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e 67 number, meaning
380e0 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e 20 , and operation
380f0 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e of all subsequen
38100 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a t parameters..**
38110 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
38120 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75 73 ce is not for us
38130 65 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f 6e e by application
38140 73 2e 20 20 49 74 20 65 78 69 73 74 73 20 73 6f s. It exists so
38150 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72 69 lely.** for veri
38160 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65 63 fying the correc
38170 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 t operation of t
38180 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
38190 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a 2a y. Depending.**
381a0 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c 69 on how the SQLi
381b0 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f te library is co
381c0 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e 74 mpiled, this int
381d0 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f 74 erface might not
381e0 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 exist..**.** Th
381f0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 e details of the
38200 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 73 operation codes
38210 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 , their meanings
38220 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 , the parameters
38230 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20 61 .** they take, a
38240 6e 64 20 77 68 61 74 20 74 68 65 79 20 64 6f 20 nd what they do
38250 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74 20 are all subject
38260 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
38270 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c t notice..** Unl
38280 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 ike most of the
38290 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69 73 SQLite API, this
382a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 function is not
382b0 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a 2a guaranteed to.*
382c0 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69 73 * operate consis
382d0 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 20 tently from one
382e0 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e release to the n
382f0 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ext..*/.int sqli
38300 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c te3_test_control
38310 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a (int op, ...);..
38320 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
38330 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 Testing Interfac
38340 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 65 e Operation Code
38350 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
38360 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
38370 76 61 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e 20 valid operation
38380 63 6f 64 65 20 70 61 72 61 6d 65 74 65 72 73 20 code parameters
38390 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 20 66 used.** as the f
383a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
383b0 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 [sqlite3_test_c
383c0 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a ontrol()]..**.**
383d0 20 54 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 These parameter
383e0 73 20 61 6e 64 20 74 68 65 69 72 20 6d 65 61 6e s and their mean
383f0 69 6e 67 73 20 61 72 65 20 73 75 62 6a 65 63 74 ings are subject
38400 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77 69 to change.** wi
38410 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20 54 thout notice. T
38420 68 65 73 65 20 76 61 6c 75 65 73 20 61 72 65 20 hese values are
38430 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72 70 for testing purp
38440 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 70 oses only..** Ap
38450 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
38460 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f 66 d not use any of
38470 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 these parameter
38480 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c s or the.** [sql
38490 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f ite3_test_contro
384a0 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a l()] interface..
384b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
384c0 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f E_TESTCTRL_PRNG_
384d0 53 41 56 45 20 20 20 20 20 20 20 20 20 20 20 20 SAVE
384e0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 5.#define SQ
384f0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 LITE_TESTCTRL_PR
38500 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 20 20 20 NG_RESTORE
38510 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
38520 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
38530 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 20 20 20 _PRNG_RESET
38540 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 7.#def
38550 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
38560 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 53 54 20 TRL_BITVEC_TEST
38570 20 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 8.#
38580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
38590 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f 49 4e 53 STCTRL_FAULT_INS
385a0 54 41 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 TALL
385b0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 9.#define SQLITE
385c0 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e 49 47 4e _TESTCTRL_BENIGN
385d0 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20 20 _MALLOC_HOOKS
385e0 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 10.#define SQL
385f0 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 45 4e ITE_TESTCTRL_PEN
38600 44 49 4e 47 5f 42 59 54 45 20 20 20 20 20 20 20 DING_BYTE
38610 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 11.#define
38620 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
38630 41 53 53 45 52 54 20 20 20 20 20 20 20 20 20 20 ASSERT
38640 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 12.#defi
38650 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
38660 52 4c 5f 41 4c 57 41 59 53 20 20 20 20 20 20 20 RL_ALWAYS
38670 20 20 20 20 20 20 20 20 20 20 20 31 33 0a 23 64 13.#d
38680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
38690 54 43 54 52 4c 5f 52 45 53 45 52 56 45 20 20 20 TCTRL_RESERVE
386a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 14
386b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
386c0 3a 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 : SQLite Runtime
386d0 20 53 74 61 74 75 73 0a 2a 2a 20 45 58 50 45 52 Status.** EXPER
386e0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 5e 54 IMENTAL.**.** ^T
386f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
38700 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
38710 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 e runtime status
38720 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
38730 61 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 about the prefor
38740 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c mance of SQLite,
38750 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 and optionally
38760 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 to reset various
38770 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 .** highwater ma
38780 72 6b 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 rks. ^The first
38790 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 argument is an
387a0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 integer code for
387b0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 .** the specific
387c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 parameter to me
387d0 61 73 75 72 65 2e 20 20 5e 52 65 63 6f 67 6e 69 asure. ^Recogni
387e0 7a 65 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65 zed integer code
387f0 73 0a 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20 s.** are of the
38800 66 6f 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 form [SQLITE_STA
38810 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 TUS_MEMORY_USED
38820 7c 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f | SQLITE_STATUS_
38830 2e 2e 2e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 63 75 ...]..** ^The cu
38840 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 rrent value of t
38850 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
38860 72 65 74 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 returned into *p
38870 43 75 72 72 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 Current..** ^The
38880 20 68 69 67 68 65 73 74 20 72 65 63 6f