0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 C-language API
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 e. This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 ve source.** on
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 this file under
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 hanges its name
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 ude <stdarg.h>
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 the definition
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 e can call this
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 o mark those.**
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 ther deprecated
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 use deprecated
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 y. Application
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 e aware that.**
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a ed. But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 t and gone back
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 RIMENTAL../*.**
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 _NUMBER.# undef
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 SQLITE_VERSION]
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 te3.h header.**
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65 " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 umber (always 3
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 for.** SQLite3)
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 macro resolves
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 with the value
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 SION_NUMBER for
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 t is derived. E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 ither Y will.**
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 remented.** and
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 Z will be reset
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 </a>. ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 nt system. ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d RSION "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 VERS--".#define
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 D "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 rsion.**.** Thes
10b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f e interfaces pro
10c0: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e vide the same in
10d0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 formation as the
10e0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
10f0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 ],.** [SQLITE_VE
1100: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 RSION_NUMBER], a
1110: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 nd [SQLITE_SOURC
1120: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 E_ID] C preproce
1130: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 ssor macros.** b
1140: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 ut are associate
1150: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 d with the libra
1160: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 ry instead of th
1170: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 e header file.
1180: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 ^(Cautious.** pr
1190: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 ogrammers might
11a0: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 include assert()
11b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 statements in t
11c0: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e heir application
11d0: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 to.** verify th
11e0: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e at values return
11f0: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 ed by these inte
1200: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 rfaces match the
1210: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 macros in.** th
1220: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 e header, and th
1230: 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 us insure that t
1240: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
1250: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 s.** compiled wi
1260: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 th matching libr
1270: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 ary and header f
1280: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f iles..**.** <blo
1290: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
12a0: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 assert( sqlite3
12b0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
12c0: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 er()==SQLITE_VER
12d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a SION_NUMBER );.*
12e0: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 * assert( strcmp
12f0: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 (sqlite3_sourcei
1300: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 d(),SQLITE_SOURC
1310: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 E_ID)==0 );.** a
1320: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 ssert( strcmp(sq
1330: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1340: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f (),SQLITE_VERSIO
1350: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 N)==0 );.** </pr
1360: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 e></blockquote>)
1370: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
1380: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 ite3_version[] s
1390: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 tring constant c
13a0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 ontains the text
13b0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 of [SQLITE_VERS
13c0: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 ION].** macro.
13d0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 ^The sqlite3_lib
13e0: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 version() functi
13f0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 on returns a poi
1400: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 nter to the.** t
1410: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 o the sqlite3_ve
1420: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 rsion[] string c
1430: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 onstant. The sq
1440: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1450: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 ().** function i
1460: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 s provided for u
1470: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 se in DLLs since
1480: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c DLL users usual
1490: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a ly do not have.*
14a0: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 * direct access
14b0: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 to string consta
14c0: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 nts within the D
14d0: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c LL. ^The.** sql
14e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
14f0: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f number() functio
1500: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 n returns an int
1510: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a eger equal to.**
1520: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
1530: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 _NUMBER]. ^The
1540: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 sqlite3_sourceid
1550: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 20 70 6f () function a po
1560: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74 inter.** to a st
1570: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 ring constant wh
1580: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 ose value is the
1590: 20 73 61 6d 65 20 61 73 20 74 68 65 20 5b 53 51 same as the [SQ
15a0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 0a LITE_SOURCE_ID].
15b0: 2a 2a 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f ** C preprocesso
15c0: 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 r macro..**.** S
15d0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
15e0: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 _version()] and
15f0: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 [sqlite_source_i
1600: 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f d()]..*/.SQLITE_
1610: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 EXTERN const cha
1620: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f r sqlite3_versio
1630: 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 n[];.const char
1640: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 *sqlite3_libvers
1650: 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 ion(void);.const
1660: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 char *sqlite3_s
1670: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 ourceid(void);.i
1680: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 nt sqlite3_libve
1690: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 rsion_number(voi
16a0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
16b0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 REF: Test To See
16c0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 If The Library
16d0: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a Is Threadsafe.**
16e0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
16f0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 _threadsafe() fu
1700: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a nction returns z
1710: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 ero if and only
1720: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 if.** SQLite was
1730: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69 compiled mutexi
1740: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
1750: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
1760: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1770: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1780: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
1790: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
17a0: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
17b0: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
17c0: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
17d0: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
17e0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
17f0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
1800: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
1810: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
1820: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
1830: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
1840: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
1850: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
1860: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
1870: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
1880: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
1890: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
18a0: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
18b0: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
18c0: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
18d0: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
18e0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
18f0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
1900: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
1910: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
1920: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
1930: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
1940: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
1950: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
1960: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
1970: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
1980: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
1990: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
19a0: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
19b0: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
19c0: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
19d0: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
19e0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
19f0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
1a00: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
1a10: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
1a20: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
1a30: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
1a40: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
1a50: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
1a60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
1a70: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
1a80: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
1a90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1aa0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
1ab0: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
1ac0: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
1ad0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
1ae0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
1af0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1b00: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
1b10: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
1b20: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
1b30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
1b40: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
1b50: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
1b60: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
1b70: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
1b80: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
1b90: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
1ba0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
1bb0: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
1bc0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
1bd0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
1be0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
1bf0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
1c00: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
1c10: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
1c20: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e ]. ^(The return
1c30: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
1c40: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
1c50: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 afe() function s
1c60: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f hows only the co
1c70: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 mpile-time setti
1c80: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 ng of.** thread
1c90: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 safety, not any
1ca0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 run-time changes
1cb0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 to that setting
1cc0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 made by.** sqli
1cd0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e te3_config(). In
1ce0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
1cf0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
1d00: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 rom sqlite3_thre
1d10: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 adsafe().** is u
1d20: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c nchanged by call
1d30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e s to sqlite3_con
1d40: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 fig().)^.**.** S
1d50: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
1d60: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
1d70: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
1d80: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
1d90: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1da0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 _threadsafe(void
1db0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1dc0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
1dd0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a nection Handle.*
1de0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 * KEYWORDS: {dat
1df0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1e00: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e } {database conn
1e10: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 ections}.**.** E
1e20: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 ach open SQLite
1e30: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 database is repr
1e40: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 esented by a poi
1e50: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
1e60: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 nce of.** the op
1e70: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e aque structure n
1e80: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 amed "sqlite3".
1e90: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f It is useful to
1ea0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c think of an sql
1eb0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ite3.** pointer
1ec0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 as an object. T
1ed0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
1ee0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
1ef0: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 en16()], and.**
1f00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
1f10: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 ()] interfaces a
1f20: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 re its construct
1f30: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ors, and [sqlite
1f40: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 3_close()].** is
1f50: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e its destructor.
1f60: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 There are many
1f70: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 other interface
1f80: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 s (such as.** [s
1f90: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1fa0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 2()], [sqlite3_c
1fb0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
1fc0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
1fd0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
1fe0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 )] to name but t
1ff0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d hree) that are m
2000: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 ethods on an.**
2010: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a sqlite3 object..
2020: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
2030: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 t sqlite3 sqlite
2040: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3;../*.** CAPI3R
2050: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 EF: 64-Bit Integ
2060: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 er Types.** KEYW
2070: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 ORDS: sqlite_int
2080: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 64 sqlite_uint64
2090: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
20a0: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 here is no cross
20b0: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f -platform way to
20c0: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 specify 64-bit
20d0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a integer types.**
20e0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 SQLite includes
20f0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 typedefs for 64
2100: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 -bit signed and
2110: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 unsigned integer
2120: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
2130: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 ite3_int64 and s
2140: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 qlite3_uint64 ar
2150: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 e the preferred
2160: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 type definitions
2170: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f ..** The sqlite_
2180: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2190: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 _uint64 types ar
21a0: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 e supported for
21b0: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d backwards.** com
21c0: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e patibility only.
21d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
21e0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 te3_int64 and sq
21f0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 lite_int64 types
2200: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 can store integ
2210: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 er values.** bet
2220: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 ween -9223372036
2230: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 854775808 and +9
2240: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 2233720368547758
2250: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 07 inclusive. ^
2260: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 The.** sqlite3_u
2270: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2280: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 _uint64 types ca
2290: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 n store integer
22a0: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 values .** betwe
22b0: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 en 0 and +184467
22c0: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 44073709551615 i
22d0: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 nclusive..*/.#if
22e0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
22f0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 _TYPE. typedef
2300: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
2310: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a E sqlite_int64;.
2320: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
2330: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ed SQLITE_INT64_
2340: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 TYPE sqlite_uint
2350: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64;.#elif define
2360: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 d(_MSC_VER) || d
2370: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 efined(__BORLAND
2380: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f C__). typedef _
2390: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e _int64 sqlite_in
23a0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
23b0: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 nsigned __int64
23c0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
23d0: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c else. typedef l
23e0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
23f0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
2400: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f edef unsigned lo
2410: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 ng long int sqli
2420: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 te_uint64;.#endi
2430: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 f.typedef sqlite
2440: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 _int64 sqlite3_i
2450: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 nt64;.typedef sq
2460: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 lite_uint64 sqli
2470: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a te3_uint64;../*.
2480: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 ** If compiling
2490: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 for a processor
24a0: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 that lacks float
24b0: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 ing point suppor
24c0: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 t,.** substitute
24d0: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f integer for flo
24e0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a ating-point..*/.
24f0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d #ifdef SQLITE_OM
2500: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e IT_FLOATING_POIN
2510: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c T.# define doubl
2520: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a e sqlite3_int64.
2530: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
2540: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 PI3REF: Closing
2550: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 A Database Conne
2560: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ction.**.** ^The
2570: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2580: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 routine is the
2590: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 destructor for t
25a0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
25b0: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ect..** ^Calls t
25c0: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 o sqlite3_close(
25d0: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f ) return SQLITE_
25e0: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 OK if the [sqlit
25f0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a e3] object is.**
2600: 20 73 75 63 63 65 73 73 66 75 6c 6c 6c 79 20 64 successfullly d
2610: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c estroyed and all
2620: 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f associated reso
2630: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f urces are deallo
2640: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 cated..**.** App
2650: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b lications must [
2660: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2670: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c | finalize] all
2680: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2690: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ments].** and [s
26a0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
26b0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b e | close] all [
26c0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 BLOB handles] as
26d0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a sociated with.**
26e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
26f0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 bject prior to a
2700: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f ttempting to clo
2710: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 se the object.
2720: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 ^If.** sqlite3_c
2730: 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 lose() is called
2740: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 on a [database
2750: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
2760: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 still has.** ou
2770: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 tstanding [prepa
2780: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 red statements]
2790: 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 or [BLOB handles
27a0: 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 ], then it retur
27b0: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 ns.** SQLITE_BUS
27c0: 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 Y..**.** ^If [sq
27d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 lite3_close()] i
27e0: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 s invoked while
27f0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
2800: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 open,.** the tr
2810: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 ansaction is aut
2820: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
2830: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
2840: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f e C parameter to
2850: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
2860: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 C)] must be eith
2870: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 er a NULL.** poi
2880: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 nter or an [sqli
2890: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e te3] object poin
28a0: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ter obtained.**
28b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 from [sqlite3_op
28c0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
28d0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a open16()], or.**
28e0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
28f0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 2()], and not pr
2900: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e eviously closed.
2910: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c .** ^Calling sql
2920: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 ite3_close() wit
2930: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
2940: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a argument is a .
2950: 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f ** harmless no-o
2960: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 p..*/.int sqlite
2970: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 3_close(sqlite3
2980: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 *);../*.** The t
2990: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 ype for a callba
29a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 ck function..**
29b0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 This is legacy a
29c0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 nd deprecated.
29d0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 It is included f
29e0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a or historical.**
29f0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 compatibility a
2a00: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 nd is not docume
2a10: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 nted..*/.typedef
2a20: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 int (*sqlite3_c
2a30: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 allback)(void*,i
2a40: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a nt,char**, char*
2a50: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2a60: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 REF: One-Step Qu
2a70: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e ery Execution In
2a80: 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 terface.**.** Th
2a90: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
2aa0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 interface is a
2ab0: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 convenience wrap
2ac0: 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 per around.** [s
2ad0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2ae0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 2()], [sqlite3_s
2af0: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c tep()], and [sql
2b00: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
2b10: 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 ,.** that allows
2b20: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
2b30: 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 to run multiple
2b40: 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 statements of SQ
2b50: 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 L.** without hav
2b60: 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 ing to use a lot
2b70: 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a of C code. .**.
2b80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2b90: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 exec() interface
2ba0: 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f runs zero or mo
2bb0: 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 re UTF-8 encoded
2bc0: 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 ,.** semicolon-s
2bd0: 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 eparate SQL stat
2be0: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e ements passed in
2bf0: 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d to its 2nd argum
2c00: 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 ent,.** in the c
2c10: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 ontext of the [d
2c20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2c30: 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 on] passed in as
2c40: 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 its 1st.** argu
2c50: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 ment. ^If the c
2c60: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
2c70: 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 of the 3rd argu
2c80: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 ment to.** sqlit
2c90: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 e3_exec() is not
2ca0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 NULL, then it i
2cb0: 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 s invoked for ea
2cc0: 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a ch result row.**
2cd0: 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 coming out of t
2ce0: 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c he evaluated SQL
2cf0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 statements. ^T
2d00: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 he 4th argument
2d10: 74 6f 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 to.** to sqlite3
2d20: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 _exec() is relay
2d30: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 ed through to th
2d40: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f e 1st argument o
2d50: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 f each.** callba
2d60: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 ck invocation.
2d70: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
2d80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 pointer to sqli
2d90: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
2da0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 NULL, then no c
2db0: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 allback is ever
2dc0: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 invoked and resu
2dd0: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 lt rows are.** i
2de0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 gnored..**.** ^I
2df0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
2e00: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 s while evaluati
2e10: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ng the SQL state
2e20: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 ments passed int
2e30: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
2e40: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 c(), then execut
2e50: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 ion of the curre
2e60: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f nt statement sto
2e70: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 ps and.** subseq
2e80: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 uent statements
2e90: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 are skipped. ^I
2ea0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
2eb0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
2ec0: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 xec().** is not
2ed0: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 NULL then any er
2ee0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 ror message is w
2ef0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f ritten into memo
2f00: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ry obtained.** f
2f10: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
2f20: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 loc()] and passe
2f30: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 d back through t
2f40: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
2f50: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 ..** To avoid me
2f60: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 mory leaks, the
2f70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
2f80: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 ld invoke [sqlit
2f90: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e e3_free()].** on
2fa0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
2fb0: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
2fc0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 through the 5th
2fd0: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 parameter of.**
2fe0: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 of sqlite3_exec(
2ff0: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f ) after the erro
3000: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
3010: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 is no longer ne
3020: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 eded..** ^If the
3030: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
3040: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3050: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 is not NULL and
3060: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 no errors.** oc
3070: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 cur, then sqlite
3080: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 3_exec() sets th
3090: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 e pointer in its
30a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
30b0: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 o.** NULL before
30c0: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a returning..**.*
30d0: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 * ^If an sqlite3
30e0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
30f0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
3100: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 o, the sqlite3_e
3110: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 xec().** routine
3120: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
3130: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e ABORT without in
3140: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 voking the callb
3150: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a ack again and.**
3160: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 without running
3170: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 any subsequent
3180: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
3190: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 **.** ^The 2nd a
31a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
31b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
31c0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
31d0: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
31e0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
31f0: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 he result. ^The
3200: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 3rd argument to
3210: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 the sqlite3_exe
3220: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 c().** callback
3230: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
3240: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
3250: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 gs obtained as i
3260: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 f from.** [sqlit
3270: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
3280: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 ], one for each
3290: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 column. ^If an
32a0: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 element of a.**
32b0: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 result row is NU
32c0: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 LL then the corr
32d0: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 esponding string
32e0: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 pointer for the
32f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3300: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 () callback is a
3310: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
3320: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e ^The 4th argumen
3330: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 t to the.** sqli
3340: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3350: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 ack is an array
3360: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 of pointers to s
3370: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 trings where eac
3380: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 h.** entry repre
3390: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f sents the name o
33a0: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 f corresponding
33b0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 result column as
33c0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
33d0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d m [sqlite3_colum
33e0: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_name()]..**.**
33f0: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 ^If the 2nd par
3400: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3410: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 3_exec() is a NU
3420: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f LL pointer, a po
3430: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 inter.** to an e
3440: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 mpty string, or
3450: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 a pointer that c
3460: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 ontains only whi
3470: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a tespace and/or .
3480: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c ** SQL comments,
3490: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 then no SQL sta
34a0: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c tements are eval
34b0: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 uated and the da
34c0: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 tabase.** is not
34d0: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 changed..**.**
34e0: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a Restrictions:.**
34f0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
3500: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
3510: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 must insure tha
3520: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 t the 1st parame
3530: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3540: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 xec().** is
3550: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 a valid and ope
3560: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
3570: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e ection]..** <li>
3580: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
3590: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 must not close
35a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
35b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
35c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 by.** the 1
35d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
35e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 sqlite3_exec() w
35f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 hile sqlite3_exe
3600: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a c() is running..
3610: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c ** <li> The appl
3620: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
3630: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 modify the SQL
3640: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 statement text p
3650: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 assed into.**
3660: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d the 2nd param
3670: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
3680: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c exec() while sql
3690: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 ite3_exec() is r
36a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e unning..** </ul>
36b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
36c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
36d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
36e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
36f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
3700: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
3710: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
3720: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3730: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
3740: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
3750: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
3760: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
3770: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
3780: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
3790: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
37a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
37b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
37c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
37d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
37e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
37f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
3800: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3810: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
3820: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
3830: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3840: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
3850: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
3860: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d _OK {error code}
3870: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a {error codes}.*
3880: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 * KEYWORDS: {res
3890: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c ult code} {resul
38a0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d t codes}.**.** M
38b0: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 any SQLite funct
38c0: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 ions return an i
38d0: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f nteger result co
38e0: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 de from the set
38f0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e shown.** here in
3900: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 order to indica
3910: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 tes success or f
3920: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 ailure..**.** Ne
3930: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 w error codes ma
3940: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
3950: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
3960: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 SQLite..**.** S
3970: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
3980: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 _IOERR_READ | ex
3990: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
39a0: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 des].*/.#define
39b0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 SQLITE_OK
39c0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 0 /* Succe
39d0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a ssful result */.
39e0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d /* beginning-of-
39f0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 error-codes */.#
3a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 define SQLITE_ER
3a10: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f ROR 1 /
3a20: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d * SQL error or m
3a30: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 issing database
3a40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3a50: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 E_INTERNAL 2
3a60: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c /* Internal l
3a70: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 ogic error in SQ
3a80: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 Lite */.#define
3a90: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 SQLITE_PERM
3aa0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 3 /* Acces
3ab0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e s permission den
3ac0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
3ad0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 QLITE_ABORT
3ae0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 4 /* Callba
3af0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 ck routine reque
3b00: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f sted an abort */
3b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3b20: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 BUSY 5
3b30: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
3b40: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 file is locked
3b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3b60: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 E_LOCKED 6
3b70: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e /* A table in
3b80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
3b90: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
3ba0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 ne SQLITE_NOMEM
3bb0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 7 /* A
3bc0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 malloc() failed
3bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3be0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 E_READONLY 8
3bf0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f /* Attempt to
3c00: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c write a readonl
3c10: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 y database */.#d
3c20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
3c30: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a ERRUPT 9 /*
3c40: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 Operation termi
3c50: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 nated by sqlite3
3c60: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 _interrupt()*/.#
3c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
3c80: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f ERR 10 /
3c90: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 * Some kind of d
3ca0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 isk I/O error oc
3cb0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e curred */.#defin
3cc0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 e SQLITE_CORRUPT
3cd0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 11 /* The
3ce0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 database disk i
3cf0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 mage is malforme
3d00: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
3d10: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 ITE_NOTFOUND
3d20: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 12 /* NOT USED
3d30: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 . Table or recor
3d40: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 d not found */.#
3d50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
3d60: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f LL 13 /
3d70: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c * Insertion fail
3d80: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 ed because datab
3d90: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 ase is full */.#
3da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
3db0: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f NTOPEN 14 /
3dc0: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e * Unable to open
3dd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
3de0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 le */.#define SQ
3df0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 LITE_PROTOCOL
3e00: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 15 /* NOT USE
3e10: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b D. Database lock
3e20: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 protocol error
3e30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3e40: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 E_EMPTY 16
3e50: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 /* Database i
3e60: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 s empty */.#defi
3e70: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 ne SQLITE_SCHEMA
3e80: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 17 /* Th
3e90: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
3ea0: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 a changed */.#de
3eb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 fine SQLITE_TOOB
3ec0: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 IG 18 /*
3ed0: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 String or BLOB e
3ee0: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 xceeds size limi
3ef0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
3f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 ITE_CONSTRAINT
3f10: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 19 /* Abort du
3f20: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 e to constraint
3f30: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 violation */.#de
3f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d fine SQLITE_MISM
3f50: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 ATCH 20 /*
3f60: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 Data type mismat
3f70: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ch */.#define SQ
3f80: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 LITE_MISUSE
3f90: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 21 /* Library
3fa0: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c used incorrectl
3fb0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
3fc0: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 ITE_NOLFS
3fd0: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 22 /* Uses OS
3fe0: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 features not sup
3ff0: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a ported on host *
4000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4010: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 _AUTH 23
4020: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 /* Authorizati
4030: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 on denied */.#de
4040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d fine SQLITE_FORM
4050: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 AT 24 /*
4060: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 Auxiliary databa
4070: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 se format error
4080: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4090: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 E_RANGE 25
40a0: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 /* 2nd parame
40b0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
40c0: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 ind out of range
40d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
40e0: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 TE_NOTADB 2
40f0: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 6 /* File open
4100: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 ed that is not a
4110: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a database file *
4120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4130: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 _ROW 100
4140: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 /* sqlite3_ste
4150: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 p() has another
4160: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 row ready */.#de
4170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 fine SQLITE_DONE
4180: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 101 /*
4190: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
41a0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 as finished exec
41b0: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d uting */./* end-
41c0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a of-error-codes *
41d0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
41e0: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 F: Extended Resu
41f0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 lt Codes.** KEYW
4200: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 ORDS: {extended
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 error code} {ext
4220: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
4230: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 s}.** KEYWORDS:
4240: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 {extended result
4250: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 code} {extended
4260: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a result codes}.*
4270: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 *.** In its defa
4280: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
4290: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f n, SQLite API ro
42a0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e utines return on
42b0: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a e of 26 integer.
42c0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 ** [SQLITE_OK |
42d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 result codes].
42e0: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 However, experie
42f0: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 nce has shown th
4300: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 at many of.** th
4310: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ese result codes
4320: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d are too coarse-
4330: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 grained. They d
4340: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 o not provide as
4350: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 .** much informa
4360: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c tion about probl
4370: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 ems as programme
4380: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 rs might like.
4390: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a In an effort to.
43a0: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c ** address this,
43b0: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 newer versions
43c0: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 of SQLite (versi
43d0: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 on 3.3.8 and lat
43e0: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 er) include.** s
43f0: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 upport for addit
4400: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 ional result cod
4410: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 es that provide
4420: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e more detailed in
4430: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f formation.** abo
4440: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 ut errors. The e
4450: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
4460: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 odes are enabled
4470: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
4480: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 on a per databas
4490: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 e connection bas
44a0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 is using the.**
44b0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
44c0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
44d0: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d ] API..**.** Som
44e0: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 e of the availab
44f0: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 le extended resu
4500: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 lt codes are lis
4510: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 ted here..** One
4520: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 may expect the
4530: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 number of extend
4540: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
4550: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a will be expand.*
4560: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f * over time. So
4570: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 ftware that uses
4580: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
4590: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 codes should ex
45a0: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e pect.** to see n
45b0: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ew result codes
45c0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
45d0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
45e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f .** The SQLITE_O
45f0: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 K result code wi
4600: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 ll never be exte
4610: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 nded. It will a
4620: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 lways.** be exac
4630: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 tly zero..*/.#de
4640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4650: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 R_READ
4660: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4670: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 R | (1<<8)).#def
4680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4690: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 _SHORT_READ
46a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
46b0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
46c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
46d0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 WRITE
46e0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
46f0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (3<<8)).#defin
4700: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 e SQLITE_IOERR_F
4710: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 SYNC
4720: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4730: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (4<<8)).#define
4740: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
4750: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 R_FSYNC
4760: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4770: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (5<<8)).#define
4780: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 SQLITE_IOERR_TRU
4790: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 NCATE (
47a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
47b0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
47c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 QLITE_IOERR_FSTA
47d0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 T (S
47e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 QLITE_IOERR | (7
47f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
4800: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 LITE_IOERR_UNLOC
4810: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 K (SQ
4820: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c LITE_IOERR | (8<
4830: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4840: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b ITE_IOERR_RDLOCK
4850: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4860: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c ITE_IOERR | (9<<
4870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4880: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 TE_IOERR_DELETE
4890: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
48a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c TE_IOERR | (10<<
48b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
48c0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
48d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
48e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c TE_IOERR | (11<<
48f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4900: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 TE_IOERR_NOMEM
4910: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4920: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c TE_IOERR | (12<<
4930: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4940: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 TE_IOERR_ACCESS
4950: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4960: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c TE_IOERR | (13<<
4970: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4980: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 TE_IOERR_CHECKRE
4990: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 SERVEDLOCK (SQLI
49a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c TE_IOERR | (14<<
49b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
49c0: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 TE_IOERR_LOCK
49d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
49e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c TE_IOERR | (15<<
49f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4a00: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 TE_IOERR_CLOSE
4a10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4a20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c TE_IOERR | (16<<
4a30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4a40: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f TE_IOERR_DIR_CLO
4a50: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 SE (SQLI
4a60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c TE_IOERR | (17<<
4a70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4a80: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 TE_LOCKED_SHARED
4a90: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 CACHE (SQLI
4aa0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c TE_LOCKED | (1<<
4ab0: 38 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8) )../*.** CAPI
4ac0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 3REF: Flags For
4ad0: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 File Open Operat
4ae0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
4af0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 bit values are
4b00: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
4b10: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 in the.** 3rd p
4b20: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
4b30: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
4b40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e ()] interface an
4b50: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 d.** in the 4th
4b60: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
4b70: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 xOpen method of
4b80: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
4b90: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f _vfs] object..*/
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4bb0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
4bc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
4bd0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4be0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4c00: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
4c10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
4c20: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4c30: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4c50: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
4c60: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
4c70: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4c80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ca0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
4cb0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
4cc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ce0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
4cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
4d00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4d20: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
4d30: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
4d40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4d60: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
4d70: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
4d80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4da0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
4db0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
4dc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4de0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
4df0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
4e00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4e10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4e20: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
4e30: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
4e40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4e50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4e60: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
4e70: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
4e80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ea0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
4eb0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
4ec0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ee0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
4ef0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
4f00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4f10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4f30: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
4f40: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
4f50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4f60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4f70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4f80: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
4f90: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
4fa0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4fb0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4fc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4fd0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
4fe0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
4ff0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5000: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5010: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
5020: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 : Device Charact
5030: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 eristics.**.** T
5040: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69 he xDeviceCapabi
5050: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 lities method of
5060: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
5070: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a _methods].** obj
5080: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 ect returns an i
5090: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
50a0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 a vector of the
50b0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c these.** bit val
50c0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 ues expressing I
50d0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 /O characteristi
50e0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 cs of the mass s
50f0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 torage.** device
5100: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 that holds the
5110: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 file that the [s
5120: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5130: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e s].** refers to.
5140: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
5150: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
5160: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
5170: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
5180: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
5190: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
51a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
51b0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
51c0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
51d0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
51e0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
51f0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
5200: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
5210: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
5220: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
5230: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
5240: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
5250: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
5260: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
5270: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
5280: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
5290: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
52a0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
52b0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
52c0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
52d0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
52e0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
52f0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
5300: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5310: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
5320: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
5330: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
5340: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
5350: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
5360: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
5370: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f to xWrite()..*/
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5390: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 IOCAP_ATOMIC
53a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
53b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
53c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 IOCAP_ATOMIC512
53d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
53e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
53f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 IOCAP_ATOMIC1K
5400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
5410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5420: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 IOCAP_ATOMIC2K
5430: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0x00000008
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5450: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 IOCAP_ATOMIC4K
5460: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
5470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5480: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 IOCAP_ATOMIC8K
5490: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
54a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
54b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 IOCAP_ATOMIC16K
54c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
54e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 IOCAP_ATOMIC32K
54f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5510: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 IOCAP_ATOMIC64K
5520: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5540: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
5550: 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 D 0x00000200
5560: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5570: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
5580: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0x00000400
5590: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
55a0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c : File Locking L
55b0: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 evels.**.** SQLi
55c0: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 te uses one of t
55d0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c hese integer val
55e0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e ues as the secon
55f0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
5600: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 calls it makes
5610: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 to the xLock() a
5620: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 nd xUnlock() met
5630: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 hods.** of an [s
5640: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5650: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 s] object..*/.#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
5670: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 K_NONE
5680: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
5690: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 _LOCK_SHARED
56a0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
56b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 LITE_LOCK_RESERV
56c0: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e ED 2.#defin
56d0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 e SQLITE_LOCK_PE
56e0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 NDING 3.#d
56f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
5700: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 K_EXCLUSIVE
5710: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 4../*.** CAPI3RE
5720: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 F: Synchronizati
5730: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a on Type Flags.**
5740: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 .** When SQLite
5750: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e invokes the xSyn
5760: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e c() method of an
5770: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f .** [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
5790: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e it uses a combin
57a0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 ation of.** thes
57b0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
57c0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 as the second a
57d0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 rgument..**.** W
57e0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 hen the SQLITE_S
57f0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 YNC_DATAONLY fla
5800: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 g is used, it me
5810: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ans that the.**
5820: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f sync operation o
5830: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 nly needs to flu
5840: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 sh data to mass
5850: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a storage. Inode.
5860: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e ** information n
5870: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 eed not be flush
5880: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 ed. If the lower
5890: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 four bits of th
58a0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 e flag.** equal
58b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
58c0: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 AL, that means t
58d0: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 o use normal fsy
58e0: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a nc() semantics..
58f0: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 ** If the lower
5900: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 four bits equal
5910: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
5920: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 , that means.**
5930: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 to use Mac OS X
5940: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 style fullsync i
5950: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 nstead of fsync(
5960: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 )..*/.#define SQ
5970: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
5980: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
5990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
59a0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
59b0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
59c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
59d0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
59e0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 010../*.** CAPI3
59f0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
5a00: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 e Open File Hand
5a10: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c le.**.** An [sql
5a20: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
5a30: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 t represents an
5a40: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 open file in the
5a50: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 .** [sqlite3_vf
5a60: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 s | OS interface
5a70: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 layer]. Indivi
5a80: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
5a90: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
5aa0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
5ab0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
5ac0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
5ad0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
5ae0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
5af0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
5b00: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
5b10: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
5b20: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
5b30: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
5b40: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
5b50: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
5b60: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
5b70: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
5b80: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
5b90: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
5ba0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
5bb0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
5bc0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
5bd0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
5be0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5bf0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
5c00: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
5c10: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
5c20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
5c30: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
5c40: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
5c50: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ds Object.**.**
5c60: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 Every file opene
5c70: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
5c80: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 3_vfs] xOpen met
5c90: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e hod populates an
5ca0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
5cb0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d e] object (or, m
5cc0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 ore commonly, a
5cd0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
5ce0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
5cf0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 ] object) with a
5d00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
5d10: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
5d20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 object..** This
5d30: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
5d40: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 he methods used
5d50: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
5d60: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a us operations.**
5d70: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
5d80: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 n file represent
5d90: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
5da0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e e3_file] object.
5db0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f .**.** If the xO
5dc0: 70 65 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20 pen method sets
5dd0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
5de0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e .pMethods elemen
5df0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e t .** to a non-N
5e00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
5e10: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f n the sqlite3_io
5e20: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 _methods.xClose
5e30: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 method.** may be
5e40: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 invoked even if
5e50: 20 74 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 the xOpen repor
5e60: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c ted that it fail
5e70: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 ed. The.** only
5e80: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 way to prevent
5e90: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 a call to xClose
5ea0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 following a fai
5eb0: 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 led xOpen.** is
5ec0: 66 6f 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f for the xOpen to
5ed0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 set the sqlite3
5ee0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
5ef0: 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a lement to NULL..
5f00: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 **.** The flags
5f10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e argument to xSyn
5f20: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 c may be one of
5f30: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 [SQLITE_SYNC_NOR
5f40: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 MAL] or.** [SQLI
5f50: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 TE_SYNC_FULL].
5f60: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 The first choice
5f70: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 is the normal f
5f80: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 sync()..** The s
5f90: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 econd choice is
5fa0: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 a Mac OS X style
5fb0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 fullsync. The
5fc0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 [SQLITE_SYNC_DAT
5fd0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d AONLY].** flag m
5fe0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f ay be ORed in to
5ff0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f indicate that o
6000: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 nly the data of
6010: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 the file.** and
6020: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 not its inode ne
6030: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 eds to be synced
6040: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 ..**.** The inte
6050: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c ger values to xL
6060: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
6070: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a k() are one of.*
6080: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
6090: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
60a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
60b0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c TE_LOCK_SHARED],
60c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
60d0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c _LOCK_RESERVED],
60e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
60f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
6100: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 or.** <li> [SQLI
6110: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
6120: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 E]..** </ul>.**
6130: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 xLock() increase
6140: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c s the lock. xUnl
6150: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 ock() decreases
6160: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 the lock..** The
6170: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c xCheckReservedL
6180: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 ock() method che
6190: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 cks whether any
61a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
61b0: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 ion,.** either i
61c0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f n this process o
61d0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 r in some other
61e0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 process, is hold
61f0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a ing a RESERVED,.
6200: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 ** PENDING, or E
6210: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e XCLUSIVE lock on
6220: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 the file. It r
6230: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 eturns true.** i
6240: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 f such a lock ex
6250: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f ists and false o
6260: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 therwise..**.**
6270: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c The xFileControl
6280: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 () method is a g
6290: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 eneric interface
62a0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 that allows cus
62b0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 tom.** VFS imple
62c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 mentations to di
62d0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 rectly control a
62e0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e n open file usin
62f0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
6300: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
6310: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 ] interface. Th
6320: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 e second "op" ar
6330: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 gument is an.**
6340: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 integer opcode.
6350: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
6360: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 ent is a generic
6370: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 pointer intende
6380: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f d to.** point to
6390: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 a structure tha
63a0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 t may contain ar
63b0: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 guments or space
63c0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 in which to.**
63d0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c write return val
63e0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 ues. Potential
63f0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f uses for xFileCo
6400: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 ntrol() might be
6410: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f .** functions to
6420: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 enable blocking
6430: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 locks with time
6440: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 outs, to change
6450: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 the.** locking s
6460: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 trategy (for exa
6470: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d mple to use dot-
6480: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 file locks), to
6490: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 inquire.** about
64a0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 the status of a
64b0: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 lock, or to bre
64c0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 ak stale locks.
64d0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 The SQLite.** c
64e0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c ore reserves all
64f0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 opcodes less th
6500: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f an 100 for its o
6510: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 wn use..** A [SQ
6520: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
6530: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f TATE | list of o
6540: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 pcodes] less tha
6550: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 n 100 is availab
6560: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 le..** Applicati
6570: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 ons that define
6580: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f a custom xFileCo
6590: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f ntrol method sho
65a0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a uld use opcodes.
65b0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 ** greater than
65c0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 100 to avoid con
65d0: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 flicts..**.** Th
65e0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 e xSectorSize()
65f0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 method returns t
6600: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f he sector size o
6610: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 f the.** device
6620: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 that underlies t
6630: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 he file. The se
6640: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 ctor size is the
6650: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 .** minimum writ
6660: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 e that can be pe
6670: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 rformed without
6680: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 disturbing.** ot
6690: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 her bytes in the
66a0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 file. The xDev
66b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
66c0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 cs().** method r
66d0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 eturns a bit vec
66e0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 tor describing b
66f0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a ehaviors of the.
6700: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 ** underlying de
6710: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e vice:.**.** <ul>
6720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
6730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a _IOCAP_ATOMIC].*
6740: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
6750: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a OCAP_ATOMIC512].
6760: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6770: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a IOCAP_ATOMIC1K].
6780: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6790: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a IOCAP_ATOMIC2K].
67a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
67b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a IOCAP_ATOMIC4K].
67c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
67d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a IOCAP_ATOMIC8K].
67e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
67f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d IOCAP_ATOMIC16K]
6800: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
6810: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
6820: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
6830: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
6840: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
6850: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
6860: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 PEND].** <li> [S
6870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
6880: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e ENTIAL].** </ul>
6890: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
68a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
68b0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
68c0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
68d0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
68e0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
68f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6900: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
6910: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
6920: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
6930: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
6940: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
6950: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
6960: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
6970: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
6980: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
6990: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
69a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
69b0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
69c0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
69d0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
69e0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
69f0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
6a00: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
6a10: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
6a20: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
6a30: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
6a40: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
6a50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6a60: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
6a70: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6a80: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
6a90: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
6aa0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
6ab0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
6ac0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a to xWrite()..**
6ad0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 .** If xRead() r
6ae0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f eturns SQLITE_IO
6af0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 ERR_SHORT_READ i
6b00: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c t must also fill
6b10: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 .** in the unrea
6b20: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 d portions of th
6b30: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 e buffer with ze
6b40: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 ros. A VFS that
6b50: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 .** fails to zer
6b60: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
6b70: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f ds might seem to
6b80: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c work. However,
6b90: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a .** failure to z
6ba0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
6bb0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 eads will eventu
6bc0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 ally lead to.**
6bd0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 database corrupt
6be0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
6bf0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
6c00: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 o_methods sqlite
6c10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 3_io_methods;.st
6c20: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
6c30: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 methods {. int
6c40: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
6c50: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
6c60: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
6c70: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 (*xRead)(sqlite3
6c80: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 _file*, void*, i
6c90: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
6ca0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
6cb0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 int (*xWrite)(s
6cc0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f qlite3_file*, co
6cd0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 nst void*, int i
6ce0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
6cf0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
6d00: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 (*xTruncate)(sq
6d10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
6d20: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 ite3_int64 size)
6d30: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
6d40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
6d50: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e int flags);. in
6d60: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 t (*xFileSize)(s
6d70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
6d80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 lite3_int64 *pSi
6d90: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f ze);. int (*xLo
6da0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
6db0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
6dc0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 *xUnlock)(sqlite
6dd0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
6de0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 int (*xCheckRes
6df0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 ervedLock)(sqlit
6e00: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 e3_file*, int *p
6e10: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
6e20: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 *xFileControl)(s
6e30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
6e40: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 t op, void *pArg
6e50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 );. int (*xSect
6e60: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f orSize)(sqlite3_
6e70: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
6e80: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
6e90: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f istics)(sqlite3_
6ea0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 file*);. /* Add
6eb0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 itional methods
6ec0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
6ed0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
6ee0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
6ef0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 I3REF: Standard
6f00: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 File Control Opc
6f10: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 odes.**.** These
6f20: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
6f30: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 ts are opcodes f
6f40: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 or the xFileCont
6f50: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 rol method.** of
6f60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
6f70: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
6f80: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 and for the [sq
6f90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
6fa0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 ol()].** interfa
6fb0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 ce..**.** The [S
6fc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b QLITE_FCNTL_LOCK
6fd0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 STATE] opcode is
6fe0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 used for debugg
6ff0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 ing. This.** op
7000: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 code causes the
7010: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
7020: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 hod to write the
7030: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f current state o
7040: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f f.** the lock (o
7050: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f ne of [SQLITE_LO
7060: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 CK_NONE], [SQLIT
7070: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a E_LOCK_SHARED],.
7080: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ** [SQLITE_LOCK_
7090: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 RESERVED], [SQLI
70a0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
70b0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 , or [SQLITE_LOC
70c0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a K_EXCLUSIVE]).**
70d0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 into an integer
70e0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 that the pArg a
70f0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 rgument points t
7100: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 o. This capabili
7110: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 ty.** is used du
7120: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 ring testing and
7130: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 only needs to b
7140: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e e supported when
7150: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 SQLITE_TEST.**
7160: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 is defined..*/.#
7170: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
7180: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 NTL_LOCKSTATE
7190: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
71a0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 QLITE_GET_LOCKPR
71b0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 OXYFILE 2.#
71c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
71d0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
71e0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
71f0: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f QLITE_LAST_ERRNO
7200: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a 4..
7210: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
7220: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a Mutex Handle.**.
7230: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 ** The mutex mod
7240: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 ule within SQLit
7250: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 e defines [sqlit
7260: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 e3_mutex] to be
7270: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 an.** abstract t
7280: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 ype for a mutex
7290: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c object. The SQL
72a0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c ite core never l
72b0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 ooks.** at the i
72c0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e nternal represen
72d0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 tation of an [sq
72e0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 lite3_mutex]. I
72f0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 t only.** deals
7300: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f with pointers to
7310: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
7320: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a tex] object..**.
7330: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 ** Mutexes are c
7340: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 reated using [sq
7350: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
7360: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 c()]..*/.typedef
7370: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
7380: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 mutex sqlite3_mu
7390: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 tex;../*.** CAPI
73a0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
73b0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ce Object.**.**
73c0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
73d0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
73e0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
73f0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 e interface betw
7400: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 een.** the SQLit
7410: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 e core and the u
7420: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 nderlying operat
7430: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 ing system. The
7440: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 "vfs".** in the
7450: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a name of the obj
7460: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 ect stands for "
7470: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 virtual file sys
7480: 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tem"..**.** The
7490: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 value of the iVe
74a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 rsion field is i
74b0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d nitially 1 but m
74c0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a ay be larger in.
74d0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f ** future versio
74e0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 ns of SQLite. A
74f0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
7500: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
7510: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 to this.** obje
7520: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 ct when the iVer
7530: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e sion value is in
7540: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 creased. Note t
7550: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
7560: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
7570: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
7580: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
7590: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 ansaction betwee
75a0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 n.** SQLite vers
75b0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e ion 3.5.9 and 3.
75c0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 6.0 and yet the
75d0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 iVersion field w
75e0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 as not.** modifi
75f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
7600: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
7610: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
7620: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 subclassed [sqli
7630: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 te3_file].** str
7640: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 ucture used by t
7650: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 his VFS. mxPath
7660: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 name is the maxi
7670: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a mum length of.**
7680: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 a pathname in t
7690: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 his VFS..**.** R
76a0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 egistered sqlite
76b0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 3_vfs objects ar
76c0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b e kept on a link
76d0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 ed list formed b
76e0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 y.** the pNext p
76f0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 ointer. The [sq
7700: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
7710: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 er()].** and [sq
7720: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
7730: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 ster()] interfac
7740: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c es manage this l
7750: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 ist.** in a thre
7760: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 ad-safe way. Th
7770: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 e [sqlite3_vfs_f
7780: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ind()] interface
7790: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 .** searches the
77a0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 list. Neither
77b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
77c0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 code nor the VFS
77d0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
77e0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 on should use th
77f0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
7800: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 .**.** The pNext
7810: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e field is the on
7820: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 ly field in the
7830: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 sqlite3_vfs.** s
7840: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 tructure that SQ
7850: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d Lite will ever m
7860: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 odify. SQLite w
7870: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a ill only access.
7880: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ** or modify thi
7890: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f s field while ho
78a0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c lding a particul
78b0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e ar static mutex.
78c0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
78d0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
78e0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 modify anything
78f0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 within the sqli
7900: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 te3_vfs.** objec
7910: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 t once the objec
7920: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 t has been regis
7930: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tered..**.** The
7940: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c zName field hol
7950: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ds the name of t
7960: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 he VFS module.
7970: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a The name must.**
7980: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 be unique acros
7990: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 s all VFS module
79a0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 s..**.** SQLite
79b0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 will guarantee t
79c0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d hat the zFilenam
79d0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 e parameter to x
79e0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 Open.** is eithe
79f0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
7a00: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 or string obtai
7a10: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c ned.** from xFul
7a20: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 lPathname(). SQ
7a30: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 Lite further gua
7a40: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 rantees that.**
7a50: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 the string will
7a60: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 be valid and unc
7a70: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c hanged until xCl
7a80: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c ose() is.** call
7a90: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 ed. Because of t
7aa0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
7ab0: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 ence,.** the [sq
7ac0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 lite3_file] can
7ad0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 safely store a p
7ae0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ointer to the.**
7af0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 filename if it
7b00: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 needs to remembe
7b10: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 r the filename f
7b20: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a or some reason..
7b30: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e ** If the zFilen
7b40: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
7b50: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c xOpen is a NULL
7b60: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f pointer then xO
7b70: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 pen.** must inve
7b80: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f nt its own tempo
7b90: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 rary name for th
7ba0: 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 e file. Wheneve
7bb0: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e r the .** xFilen
7bc0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
7bd0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c NULL it will al
7be0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 so be the case t
7bf0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 hat the.** flags
7c00: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 parameter will
7c10: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f include [SQLITE_
7c20: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
7c30: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 SE]..**.** The f
7c40: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
7c50: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 xOpen() include
7c60: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 s all bits set i
7c70: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 n.** the flags a
7c80: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
7c90: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 te3_open_v2()].
7ca0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f Or if [sqlite3_
7cb0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 open()].** or [s
7cc0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
7cd0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 is used, then f
7ce0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 lags includes at
7cf0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 least.** [SQLIT
7d00: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
7d10: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ] | [SQLITE_OPEN
7d20: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 _CREATE]. .** If
7d30: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 xOpen() opens a
7d40: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 file read-only
7d50: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f then it sets *pO
7d60: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e utFlags to.** in
7d70: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 clude [SQLITE_OP
7d80: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f EN_READONLY]. O
7d90: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f ther bits in *pO
7da0: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 utFlags may be s
7db0: 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 et..**.** SQLite
7dc0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f will also add o
7dd0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
7de0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
7df0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c xOpen().** call
7e00: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
7e10: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 he object being
7e20: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 opened:.**.** <u
7e30: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c l>.** <li> [SQL
7e40: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
7e50: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
7e60: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
7e70: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
7e80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
7e90: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
7ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
7eb0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
7ec0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
7ed0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 RANSIENT_DB].**
7ee0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
7ef0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a EN_SUBJOURNAL].*
7f00: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
7f10: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
7f20: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a NAL].** </ul>.**
7f30: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f .** The file I/O
7f40: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
7f50: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 can use the obje
7f60: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f ct type flags to
7f70: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 .** change the w
7f80: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 ay it deals with
7f90: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 files. For exa
7fa0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 mple, an applica
7fb0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 tion.** that doe
7fc0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 s not care about
7fd0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 crash recovery
7fe0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 or rollback migh
7ff0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 t make.** the op
8000: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 en of a journal
8010: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 file a no-op. W
8020: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f rites to this jo
8030: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 urnal would.** a
8040: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 lso be no-ops, a
8050: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 nd any attempt t
8060: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e o read the journ
8070: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a al would return.
8080: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e ** SQLITE_IOERR.
8090: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 Or the impleme
80a0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 ntation might re
80b0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 cognize that a d
80c0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
80d0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 will be doing pa
80e0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f ge-aligned secto
80f0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 r reads and writ
8100: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a es in a random.*
8110: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 * order and set
8120: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 up its I/O subsy
8130: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 stem accordingly
8140: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d ..**.** SQLite m
8150: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e ight also add on
8160: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
8170: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
8180: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a xOpen method:.**
8190: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
81b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 LETEONCLOSE].**
81c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 <li> [SQLITE_OPE
81d0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 N_EXCLUSIVE].**
81e0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
81f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
8200: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 ETEONCLOSE] flag
8210: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 means the file
8220: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c should be.** del
8230: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 eted when it is
8240: 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51 closed. The [SQ
8250: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
8260: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c ONCLOSE].** will
8270: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 be set for TEMP
8280: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 databases, jou
8290: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 rnals and for su
82a0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a bjournals..**.**
82b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 The [SQLITE_OPE
82c0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 N_EXCLUSIVE] fla
82d0: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 g is always used
82e0: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a in conjunction.
82f0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ** with the [SQL
8300: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
8310: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 flag, which are
8320: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a both directly.*
8330: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 * analogous to t
8340: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f he O_EXCL and O_
8350: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 CREAT flags of t
8360: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a he POSIX open().
8370: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c ** API. The SQL
8380: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
8390: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 VE flag, when pa
83a0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a ired with the .*
83b0: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 * SQLITE_OPEN_CR
83c0: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f EATE, is used to
83d0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 indicate that f
83e0: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 ile should alway
83f0: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c s.** be created,
8400: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 and that it is
8410: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 an error if it a
8420: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a lready exists..*
8430: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f * It is <i>not</
8440: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 i> used to indic
8450: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f ate the file sho
8460: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a uld be opened .*
8470: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 * for exclusive
8480: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74 access..**.** At
8490: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 least szOsFile
84a0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 bytes of memory
84b0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 are allocated by
84c0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f SQLite.** to ho
84d0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 ld the [sqlite3
84e0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 _file] structure
84f0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 passed as the t
8500: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 hird.** argument
8510: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 to xOpen. The
8520: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 xOpen method doe
8530: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a s not have to.**
8540: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 allocate the st
8550: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 ructure; it shou
8560: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 ld just fill it
8570: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a in. Note that.*
8580: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 * the xOpen meth
8590: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 od must set the
85a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
85b0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a thods to either.
85c0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 ** a valid [sqli
85d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
85e0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c object or to NUL
85f0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 L. xOpen must d
8600: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 o.** this even i
8610: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 f the open fails
8620: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 . SQLite expect
8630: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 s that the sqlit
8640: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
8650: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c .** element will
8660: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 be valid after
8670: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 xOpen returns re
8680: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 gardless of the
8690: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 success.** or fa
86a0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 ilure of the xOp
86b0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 en call..**.** T
86c0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
86d0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d t to xAccess() m
86e0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 ay be [SQLITE_AC
86f0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 CESS_EXISTS].**
8700: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 to test for the
8710: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 existence of a f
8720: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ile, or [SQLITE_
8730: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
8740: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 ] to.** test whe
8750: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 ther a file is r
8760: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
8770: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 able, or [SQLITE
8780: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a _ACCESS_READ].**
8790: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 to test whether
87a0: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 a file is at le
87b0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 ast readable.
87c0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 The file can be
87d0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a a.** directory..
87e0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
87f0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 l always allocat
8800: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 e at least mxPat
8810: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f hname+1 bytes fo
8820: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 r the.** output
8830: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 buffer xFullPath
8840: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 name. The exact
8850: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 size of the out
8860: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
8870: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 also passed as
8880: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 a parameter to b
8890: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 oth methods. If
88a0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
88b0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 er.** is not lar
88c0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 ge enough, [SQLI
88d0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f TE_CANTOPEN] sho
88e0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e uld be returned.
88f0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a Since this is.*
8900: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 * handled as a f
8910: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 atal error by SQ
8920: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d Lite, vfs implem
8930: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 entations should
8940: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 endeavor.** to
8950: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 prevent this by
8960: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 setting mxPathna
8970: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 me to a sufficie
8980: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 ntly large value
8990: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e ..**.** The xRan
89a0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 domness(), xSlee
89b0: 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e p(), and xCurren
89c0: 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 tTime() interfac
89d0: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 es.** are not st
89e0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 rictly a part of
89f0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c the filesystem,
8a00: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a but they are.**
8a10: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 included in the
8a20: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 VFS structure f
8a30: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e or completeness.
8a40: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e .** The xRandomn
8a50: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 ess() function a
8a60: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 ttempts to retur
8a70: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a n nBytes bytes.*
8a80: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 * of good-qualit
8a90: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 y randomness int
8aa0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 o zOut. The ret
8ab0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 urn value is.**
8ac0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 the actual numbe
8ad0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 r of bytes of ra
8ae0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 ndomness obtaine
8af0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 d..** The xSleep
8b00: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 () method causes
8b10: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 the calling thr
8b20: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 ead to sleep for
8b30: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 at.** least the
8b40: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f number of micro
8b50: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 seconds given.
8b60: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
8b70: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
8b80: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 urns a Julian Da
8b90: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 y Number for the
8ba0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e current date an
8bb0: 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 d time..**.*/.ty
8bc0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
8bd0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 ite3_vfs sqlite3
8be0: 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c _vfs;.struct sql
8bf0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 ite3_vfs {. int
8c00: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 iVersion;
8c10: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 /* Structu
8c20: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 re version numbe
8c30: 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 r */. int szOsF
8c40: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 ile;
8c50: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c /* Size of subcl
8c60: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 assed sqlite3_fi
8c70: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 le */. int mxPa
8c80: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 thname;
8c90: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 /* Maximum file
8ca0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 pathname length
8cb0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 */. sqlite3_vf
8cc0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f s *pNext; /
8cd0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 * Next registere
8ce0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 d VFS */. const
8cf0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 char *zName;
8d00: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
8d10: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 his virtual file
8d20: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 system */. voi
8d30: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
8d40: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 /* Pointer
8d50: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d to application-
8d60: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f specific data */
8d70: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 . int (*xOpen)(
8d80: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
8d90: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
8da0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a sqlite3_file*,.
8db0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
8dc0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 nt flags, int *p
8dd0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 OutFlags);. int
8de0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 (*xDelete)(sqli
8df0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
8e00: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
8e10: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 syncDir);. int
8e20: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 (*xAccess)(sqli
8e30: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
8e40: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
8e50: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 flags, int *pRe
8e60: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
8e70: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 FullPathname)(sq
8e80: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
8e90: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
8ea0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a nt nOut, char *z
8eb0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a Out);. void *(*
8ec0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 xDlOpen)(sqlite3
8ed0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
8ee0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 r *zFilename);.
8ef0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 void (*xDlError
8f00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8f10: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 int nByte, char
8f20: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 *zErrMsg);. voi
8f30: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 d (*(*xDlSym)(sq
8f40: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a lite3_vfs*,void*
8f50: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 , const char *zS
8f60: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 ymbol))(void);.
8f70: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 void (*xDlClose
8f80: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8f90: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a void*);. int (*
8fa0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c xRandomness)(sql
8fb0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
8fc0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 Byte, char *zOut
8fd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 );. int (*xSlee
8fe0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c p)(sqlite3_vfs*,
8ff0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 int microsecond
9000: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 s);. int (*xCur
9010: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 rentTime)(sqlite
9020: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3_vfs*, double*)
9030: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 ;. int (*xGetLa
9040: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 stError)(sqlite3
9050: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 _vfs*, int, char
9060: 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 *);. /* New fi
9070: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 elds may be appe
9080: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 nded in figure v
9090: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 ersions. The iV
90a0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 ersion. ** valu
90b0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 e will increment
90c0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 whenever this h
90d0: 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f appens. */.};../
90e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
90f0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 lags for the xAc
9100: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a cess VFS method.
9110: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
9120: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 ger constants ca
9130: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 n be used as the
9140: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
9150: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 to.** the xAcce
9160: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 ss method of an
9170: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
9180: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 ject. They dete
9190: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 rmine.** what ki
91a0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e nd of permission
91b0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 s the xAccess me
91c0: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 thod is looking
91d0: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c for..** With SQL
91e0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 ITE_ACCESS_EXIST
91f0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d S, the xAccess m
9200: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 ethod.** simply
9210: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
9220: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a he file exists..
9230: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
9240: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c CCESS_READWRITE,
9250: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
9260: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 hod.** checks wh
9270: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 ether the file i
9280: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 s both readable
9290: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a and writable..**
92a0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
92b0: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 ESS_READ, the xA
92c0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
92d0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
92e0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 he file is reada
92f0: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ble..*/.#define
9300: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
9310: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e ISTS 0.#defin
9320: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
9330: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 READWRITE 1.#def
9340: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ine SQLITE_ACCES
9350: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f S_READ 2../
9360: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
9370: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 nitialize The SQ
9380: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a Lite Library.**.
9390: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
93a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
93b0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 tine initializes
93c0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c the.** SQLite l
93d0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 ibrary. ^The sq
93e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
93f0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c routine.** deal
9400: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f locates any reso
9410: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 urces that were
9420: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c allocated by sql
9430: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
9440: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 )..** These rout
9450: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 ines are designe
9460: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 d to aid in proc
9470: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ess initializati
9480: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f on and.** shutdo
9490: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 wn on embedded s
94a0: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 ystems. Worksta
94b0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e tion application
94c0: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 s using.** SQLit
94d0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f e normally do no
94e0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 t need to invoke
94f0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 either of these
9500: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
9510: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 A call to sqlit
9520: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9530: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
9540: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a " call if it is.
9550: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d ** the first tim
9560: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
9570: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
9580: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 d during the lif
9590: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 etime of.** the
95a0: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 process, or if i
95b0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 t is the first t
95c0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 ime sqlite3_init
95d0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f ialize() is invo
95e0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 ked.** following
95f0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
9600: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
9610: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 ^(Only an effect
9620: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 ive call.** of s
9630: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9640: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 e() does any ini
9650: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c tialization. Al
9660: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a l other calls.**
9670: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f are harmless no
9680: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 -ops.)^.**.** A
9690: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
96a0: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e shutdown() is an
96b0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
96c0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 l if it is the f
96d0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 irst.** call to
96e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
96f0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 () since the las
9700: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
9710: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a lize(). ^(Only.
9720: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 ** an effective
9730: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
9740: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 shutdown() does
9750: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 any deinitializa
9760: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 tion..** All oth
9770: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 er valid calls t
9780: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
9790: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 wn() are harmles
97a0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a s no-ops.)^.**.*
97b0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
97c0: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 itialize() inter
97d0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 face is threadsa
97e0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f fe, but sqlite3_
97f0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 shutdown().** is
9800: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 not. The sqlit
9810: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e e3_shutdown() in
9820: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c terface must onl
9830: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d y be called from
9840: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 a.** single thr
9850: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b ead. All open [
9860: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
9870: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c ions] must be cl
9880: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 osed and all.**
9890: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 other SQLite res
98a0: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 ources must be d
98b0: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 eallocated prior
98c0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 to invoking.**
98d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
98e0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 ()..**.** Among
98f0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 other things, ^s
9900: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9910: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a e() will invoke.
9920: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
9930: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 it(). Similarly
9940: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 , ^sqlite3_shutd
9950: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e own().** will in
9960: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f voke sqlite3_os_
9970: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 end()..**.** ^Th
9980: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
9990: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 lize() routine r
99a0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
99b0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a K] on success..*
99c0: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 * ^If for some r
99d0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 eason, sqlite3_i
99e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 nitialize() is u
99f0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c nable to initial
9a00: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 ize.** the libra
9a10: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 ry (perhaps it i
9a20: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
9a30: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 cate a needed re
9a40: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 source such.** a
9a50: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 s a mutex) it re
9a60: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 turns an [error
9a70: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e code] other than
9a80: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
9a90: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
9aa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
9ab0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
9ac0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 internally by ma
9ad0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ny other.** SQLi
9ae0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f te interfaces so
9af0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 that an applica
9b00: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 tion usually doe
9b10: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a s not need to.**
9b20: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
9b30: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
9b40: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d ectly. For exam
9b50: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ple, [sqlite3_op
9b60: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 en()].** calls s
9b70: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9b80: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 e() so the SQLit
9b90: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 e library will b
9ba0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
9bb0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 ** initialized w
9bc0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 hen [sqlite3_ope
9bd0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 n()] is called i
9be0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 f it has not be
9bf0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 initialized.** a
9c00: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 lready. ^Howeve
9c10: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 r, if SQLite is
9c20: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
9c30: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 e [SQLITE_OMIT_A
9c40: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 UTOINIT].** comp
9c50: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c ile-time option,
9c60: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 then the automa
9c70: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c tic calls to sql
9c80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
9c90: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 ).** are omitted
9ca0: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
9cb0: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 tion must call s
9cc0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9cd0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 e() directly.**
9ce0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
9cf0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
9d00: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 interface. For
9d10: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c maximum portabil
9d20: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 ity,.** it is re
9d30: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
9d40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 pplications alwa
9d50: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ys invoke sqlite
9d60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 3_initialize().*
9d70: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 * directly prior
9d80: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 to using any ot
9d90: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
9da0: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 face. Future re
9db0: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c leases.** of SQL
9dc0: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 ite may require
9dd0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 this. In other
9de0: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 words, the behav
9df0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a ior exhibited.**
9e00: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
9e10: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
9e20: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 QLITE_OMIT_AUTOI
9e30: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d NIT] might becom
9e40: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 e the.** default
9e50: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d behavior in som
9e60: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 e future release
9e70: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
9e80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 * The sqlite3_os
9e90: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 _init() routine
9ea0: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 does operating-s
9eb0: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a ystem specific.*
9ec0: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e * initialization
9ed0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c of the SQLite l
9ee0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c ibrary. The sql
9ef0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
9f00: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 routine undoes
9f10: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 the effect of sq
9f20: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e lite3_os_init().
9f30: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a Typical tasks.
9f40: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 ** performed by
9f50: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 these routines i
9f60: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f nclude allocatio
9f70: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f n or deallocatio
9f80: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 n.** of static r
9f90: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 esources, initia
9fa0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 lization of glob
9fb0: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a al variables,.**
9fc0: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 setting up a de
9fd0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
9fe0: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 fs] module, or s
9ff0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 etting up.** a d
a000: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 efault configura
a010: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 tion using [sqli
a020: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a te3_config()]..*
a030: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
a040: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
a050: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 r invoke either
a060: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
a070: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
a080: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c os_end() directl
a090: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 y. The applicat
a0a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 ion should only
a0b0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
a0c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 3_initialize() a
a0d0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 nd sqlite3_shutd
a0e0: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 own(). The sqli
a0f0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a te3_os_init().**
a100: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 interface is ca
a110: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c lled automatical
a120: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ly by sqlite3_in
a130: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a itialize() and.*
a140: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 * sqlite3_os_end
a150: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 () is called by
a160: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
a170: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 (). Appropriate
a180: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
a190: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f ons for sqlite3_
a1a0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
a1b0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
a1c0: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f * are built into
a1d0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 SQLite when it
a1e0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 is compiled for
a1f0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f Unix, Windows, o
a200: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 r OS/2..** When
a210: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c [custom builds |
a220: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 built for other
a230: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 platforms].** (
a240: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
a250: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f E_OS_OTHER=1] co
a260: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 mpile-time.** op
a270: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 tion) the applic
a280: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c ation must suppl
a290: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 y a suitable imp
a2a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a lementation for.
a2b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
a2c0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
a2d0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 _os_end(). An a
a2e0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
a2f0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ied.** implement
a300: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
a310: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 _os_init() or sq
a320: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
a330: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 * must return [S
a340: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
a350: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 cess and some ot
a360: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d her [error code]
a370: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 upon.** failure
a380: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
a390: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 _initialize(void
a3a0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 );.int sqlite3_s
a3b0: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 hutdown(void);.i
a3c0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e nt sqlite3_os_in
a3d0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 it(void);.int sq
a3e0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 lite3_os_end(voi
a3f0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
a400: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 REF: Configuring
a410: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
a420: 61 72 79 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e ary.** EXPERIMEN
a430: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 TAL.**.** The sq
a440: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
a450: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
a460: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 to make global
a470: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
a480: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 changes to SQLi
a490: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 te in order to t
a4a0: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 une SQLite to th
a4b0: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
a4c0: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
a4d0: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 cation. The def
a4e0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
a4f0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 on is recommende
a500: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 d for most.** ap
a510: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 plications and s
a520: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 o this routine i
a530: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 s usually not ne
a540: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a cessary. It is.
a550: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 ** provided to s
a560: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c upport rare appl
a570: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e ications with un
a580: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a usual needs..**.
a590: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
a5a0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
a5b0: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 e is not threads
a5c0: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 afe. The applic
a5d0: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e ation.** must in
a5e0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 sure that no oth
a5f0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
a600: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 aces are invoked
a610: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 by other.** thr
a620: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 eads while sqlit
a630: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 e3_config() is r
a640: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 unning. Further
a650: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f more, sqlite3_co
a660: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e nfig().** may on
a670: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 ly be invoked pr
a680: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 ior to library i
a690: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 nitialization us
a6a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
a6b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 initialize()] or
a6c0: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 after shutdown
a6d0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 by [sqlite3_shut
a6e0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 down()]..** ^If
a6f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
a700: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 is called after
a710: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
a720: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f lize()] and befo
a730: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 re.** [sqlite3_s
a740: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 hutdown()] then
a750: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 it will return S
a760: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a QLITE_MISUSE..**
a770: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 Note, however,
a780: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f that ^sqlite3_co
a790: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 nfig() can be ca
a7a0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
a7b0: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
a7c0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c ation of an appl
a7d0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
a7e0: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 [sqlite3_os_init
a7f0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ()]..**.** The f
a800: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
a810: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
a820: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a ) is an integer.
a830: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
a840: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c G_SINGLETHREAD |
a850: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
a860: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 ption] that dete
a870: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 rmines.** what p
a880: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 roperty of SQLit
a890: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 e is to be confi
a8a0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 gured. Subseque
a8b0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 nt arguments.**
a8c0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
a8d0: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f n the [SQLITE_CO
a8e0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
a8f0: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f D | configuratio
a900: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 n option].** in
a910: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
a920: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 nt..**.** ^When
a930: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
a940: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
a950: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
a960: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
a970: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 OK]..** ^If the
a980: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 option is unknow
a990: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 n or SQLite is u
a9a0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 nable to set the
a9b0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 option.** then
a9c0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 this routine ret
a9d0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 urns a non-zero
a9e0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f [error code]..*/
a9f0: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
aa00: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
aa10: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e _config(int, ...
aa20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
aa30: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 EF: Configure da
aa40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
aa50: 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ns.** EXPERIMENT
aa60: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c AL.**.** The sql
aa70: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
aa80: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
aa90: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
aaa0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
aab0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
aac0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
aad0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
aae0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
aaf0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
ab00: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
ab10: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
ab20: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
ab30: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
ab40: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
ab50: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
ab60: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a gument). The.**
ab70: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
ab80: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ig() interface s
ab90: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73 hould only be us
aba0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 ed immediately a
abb0: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 fter.** the data
abc0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
abd0: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 is created using
abe0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
abf0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f ],.** [sqlite3_o
ac00: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 pen16()], or [sq
ac10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
ac20: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 . .**.** The se
ac30: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
ac40: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
ac50: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 ig(D,V,...) is
ac60: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 the.** configura
ac70: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 tion verb - an i
ac80: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 nteger code that
ac90: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a indicates what.
aca0: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 ** aspect of the
acb0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
acc0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
acd0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 configured..** T
ace0: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 he only choice f
acf0: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 or this value is
ad00: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 [SQLITE_DBCONFI
ad10: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a G_LOOKASIDE]..**
ad20: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c New verbs are l
ad30: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 ikely to be adde
ad40: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
ad50: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
ad60: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 ** Additional ar
ad70: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f guments depend o
ad80: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a n the verb..**.*
ad90: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
ada0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
adb0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
adc0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a if and only if.
add0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 ** the call is c
ade0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 onsidered succes
adf0: 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f sful..*/.SQLITE_
ae00: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
ae10: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
ae20: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ig(sqlite3*, int
ae30: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a op, ...);../*.*
ae40: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
ae50: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f ry Allocation Ro
ae60: 75 74 69 6e 65 73 0a 2a 2a 20 45 58 50 45 52 49 utines.** EXPERI
ae70: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 MENTAL.**.** An
ae80: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
ae90: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
aea0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
aeb0: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 tween SQLite.**
aec0: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 and low-level me
aed0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
aee0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
aef0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 This object is u
af00: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 sed in only one
af10: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c place in the SQL
af20: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ite interface..*
af30: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * A pointer to a
af40: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
af50: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 is object is the
af60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
af70: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
af80: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 )] when the conf
af90: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
afa0: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 is.** [SQLITE_C
afb0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 ONFIG_MALLOC] or
afc0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
afd0: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a GETMALLOC]. .**
afe0: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 By creating an
aff0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
b000: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 object.** and p
b010: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 assing it to [sq
b020: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
b030: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
b040: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 LOC]).** during
b050: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 configuration, a
b060: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 n application ca
b070: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 n specify an alt
b080: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
b090: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
b0a0: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 bsystem for SQLi
b0b0: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c te to use for al
b0c0: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 l of its.** dyna
b0d0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 mic memory needs
b0e0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
b0f0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 t SQLite comes w
b100: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 ith several [bui
b110: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
b120: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 ocators].** that
b130: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 are perfectly a
b140: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 dequate for the
b150: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a overwhelming maj
b160: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
b170: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 tions.** and tha
b180: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 t this object is
b190: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 only useful to
b1a0: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 a tiny minority
b1b0: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a of applications.
b1c0: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 ** with speciali
b1d0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 zed memory alloc
b1e0: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e ation requiremen
b1f0: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 ts. This object
b200: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 is.** also used
b210: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 during testing
b220: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 of SQLite in ord
b230: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e er to specify an
b240: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
b250: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
b260: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 that simulates
b270: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 memory out-of-me
b280: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 mory conditions
b290: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 in.** order to v
b2a0: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 erify that SQLit
b2b0: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 e recovers grace
b2c0: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a fully from such.
b2d0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a ** conditions..*
b2e0: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 *.** The xMalloc
b2f0: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f and xFree metho
b300: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b ds must work lik
b310: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 e the.** malloc(
b320: 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e ) and free() fun
b330: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 ctions from the
b340: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
b350: 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c ry..** The xReal
b360: 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 loc method must
b370: 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f work like reallo
b380: 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61 c() from the sta
b390: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a ndard C library.
b3a0: 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65 ** with the exce
b3b0: 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68 ption that if th
b3c0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
b3d0: 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 t to xRealloc is
b3e0: 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c zero,.** xReall
b3f0: 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d oc must be a no-
b400: 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 op - it must not
b410: 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c perform any all
b420: 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 ocation or.** de
b430: 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 allocation. ^SQ
b440: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 Lite guarantees
b450: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 that the second
b460: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 argument to.** x
b470: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 Realloc is alway
b480: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e s a value return
b490: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 ed by a prior ca
b4a0: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a ll to xRoundup..
b4b0: 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 ** And so in cas
b4c0: 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75 es where xRoundu
b4d0: 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 p always returns
b4e0: 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 a positive numb
b4f0: 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 er,.** xRealloc
b500: 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63 can perform exac
b510: 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64 tly as the stand
b520: 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c ard library real
b530: 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 loc() and.** sti
b540: 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 ll be in complia
b550: 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70 nce with this sp
b560: 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a ecification..**.
b570: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 ** xSize should
b580: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 return the alloc
b590: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d ated size of a m
b5a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b5b0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f .** previously o
b5c0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 btained from xMa
b5d0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 lloc or xRealloc
b5e0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 . The allocated
b5f0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 size.** is alwa
b600: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 ys at least as b
b610: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 ig as the reques
b620: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 ted size but may
b630: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a be larger..**.*
b640: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d * The xRoundup m
b650: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 ethod returns wh
b660: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 at would be the
b670: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
b680: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c f.** a memory al
b690: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 location given a
b6a0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 particular requ
b6b0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 ested size. Mos
b6c0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f t memory.** allo
b6d0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
b6e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
b6f0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 ns at least to t
b700: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 he next multiple
b710: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 .** of 8. Some
b720: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 allocators round
b730: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 up to a larger
b740: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 multiple or to a
b750: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 power of 2..**
b760: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c Every memory all
b770: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 ocation request
b780: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 coming in throug
b790: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f h [sqlite3_mallo
b7a0: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 c()].** or [sqli
b7b0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 te3_realloc()] f
b7c0: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e irst calls xRoun
b7d0: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 dup. If xRoundu
b7e0: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a p returns 0, .**
b7f0: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 that causes the
b800: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d corresponding m
b810: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b820: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 to fail..**.**
b830: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 The xInit method
b840: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
b850: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
b860: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 r. (For example
b870: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c ,.** it might al
b880: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 locate any requi
b890: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e re mutexes or in
b8a0: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 itialize interna
b8b0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 l data.** struct
b8c0: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 ures. The xShut
b8d0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 down method is i
b8e0: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 nvoked (indirect
b8f0: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ly) by.** [sqlit
b900: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 e3_shutdown()] a
b910: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f nd should deallo
b920: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 cate any resourc
b930: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 es acquired.** b
b940: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 y xInit. The pA
b950: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 ppData pointer i
b960: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e s used as the on
b970: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a ly parameter to.
b980: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 ** xInit and xSh
b990: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 utdown..**.** SQ
b9a0: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b Lite holds the [
b9b0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
b9c0: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 TIC_MASTER] mute
b9d0: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 x when it invoke
b9e0: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d s.** the xInit m
b9f0: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 ethod, so the xI
ba00: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 nit method need
ba10: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 not be threadsaf
ba20: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 e. The.** xShut
ba30: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f down method is o
ba40: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 nly called from
ba50: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
ba60: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a n()] so it does.
ba70: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 ** not need to b
ba80: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 e threadsafe eit
ba90: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 her. For all ot
baa0: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c her methods, SQL
bab0: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 ite.** holds the
bac0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 [SQLITE_MUTEX_S
bad0: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 TATIC_MEM] mutex
bae0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a as long as the.
baf0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
bb00: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e G_MEMSTATUS] con
bb10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
bb20: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 n is turned on (
bb30: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 which.** it is b
bb40: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 y default) and s
bb50: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 o the methods ar
bb60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
bb70: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 serialized..** H
bb80: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 owever, if [SQLI
bb90: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
bba0: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 TUS] is disabled
bbb0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 , then the other
bbc0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 .** methods must
bbd0: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f be threadsafe o
bbe0: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 r else make thei
bbf0: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e r own arrangemen
bc00: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c ts for.** serial
bc10: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 ization..**.** S
bc20: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
bc30: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 invoke xInit()
bc40: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 more than once w
bc50: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 ithout an interv
bc60: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f ening.** call to
bc70: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f xShutdown()..*/
bc80: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
bc90: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
bca0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f ods sqlite3_mem_
bcb0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
bcc0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
bcd0: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a ods {. void *(*
bce0: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 xMalloc)(int);
bcf0: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 /* Memory
bd00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 allocation func
bd10: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 tion */. void (
bd20: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 *xFree)(void*);
bd30: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 /* Free
bd40: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 a prior allocat
bd50: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 ion */. void *(
bd60: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a *xRealloc)(void*
bd70: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a ,int); /* Resiz
bd80: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e an allocation
bd90: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 */. int (*xSize
bda0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
bdb0: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 /* Return th
bdc0: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c e size of an all
bdd0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
bde0: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 (*xRoundup)(int
bdf0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ); /* R
be00: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 ound up request
be10: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 size to allocati
be20: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 on size */. int
be30: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 (*xInit)(void*)
be40: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 ; /* I
be50: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
be60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
be70: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 /. void (*xShut
be80: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 down)(void*);
be90: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 /* Deinitiali
bea0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
beb0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
bec0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
bed0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
bee0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 rgument to xInit
bef0: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e () and xShutdown
bf00: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 () */.};../*.**
bf10: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
bf20: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
bf30: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
bf40: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
bf50: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
bf60: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
bf70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
bf80: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
bf90: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
bfa0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
bfb0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
bfc0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
bfd0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
bfe0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
bff0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
c000: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
c010: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
c020: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
c030: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
c040: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
c050: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
c060: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
c070: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
c080: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
c090: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
c0a0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
c0b0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 at.** the call w
c0c0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c orked. The [sql
c0d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
c0e0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
c0f0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
c100: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
c110: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
c120: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
c130: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
c140: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
c150: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
c160: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
c170: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
c180: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
c190: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
c1a0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
c1b0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 ion. ^This opti
c1c0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b on sets the.** [
c1d0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
c1e0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 to Single-thread
c1f0: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
c200: 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a s, it disables.*
c210: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 * all mutexing a
c220: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 nd puts SQLite i
c230: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 nto a mode where
c240: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 it can only be
c250: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e used.** by a sin
c260: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 gle thread. ^I
c270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
c280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
c290: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
c2a0: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
c2b0: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
c2c0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
c2d0: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 hen.** it is not
c2e0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 possible to cha
c2f0: 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 nge the [threadi
c300: 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 ng mode] from it
c310: 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c s default.** val
c320: 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 ue of Single-thr
c330: 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 ead and so [sqli
c340: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
c350: 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 ll return .** [S
c360: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
c370: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 called with the
c380: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
c390: 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f NGLETHREAD.** co
c3a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
c3b0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c on.</dd>.**.** <
c3c0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
c3d0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 _MULTITHREAD</dt
c3e0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
c3f0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
c400: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
c410: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
c420: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
c430: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 ding mode] to Mu
c440: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 lti-thread. In
c450: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
c460: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 disables.** mute
c470: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 xing on [databas
c480: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
c490: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
c4a0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
c4b0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
c4c0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c on is responsibl
c4d0: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e e for serializin
c4e0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b g access to.** [
c4f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
c500: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
c510: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e red statements].
c520: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 But other mute
c530: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
c540: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 ed so that SQLit
c550: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 e will be safe t
c560: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 o use in a multi
c570: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 -threaded.** env
c580: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 ironment as long
c590: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 as no two threa
c5a0: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 ds attempt to us
c5b0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 e the same.** [d
c5c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
c5d0: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 on] at the same
c5e0: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 time. ^If SQLit
c5f0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
c600: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
c610: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
c620: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
c630: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
c640: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
c650: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 it is not possib
c660: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 le to set the Mu
c670: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 lti-thread [thre
c680: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a ading mode] and.
c690: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
c6a0: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ig()] will retur
c6b0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
c6c0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 if called with
c6d0: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f the.** SQLITE_CO
c6e0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
c6f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
c700: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
c710: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
c720: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f FIG_SERIALIZED</
c730: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
c740: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
c750: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
c760: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
c770: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
c780: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
c790: 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f Serialized. In o
c7a0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 ther words, this
c7b0: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a option enables.
c7c0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 ** all mutexes i
c7d0: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 ncluding the rec
c7e0: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 ursive.** mutexe
c7f0: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
c800: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
c810: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
c820: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
c830: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 In this mode (wh
c840: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 ich is the defau
c850: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 lt when SQLite i
c860: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
c870: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 ** [SQLITE_THREA
c880: 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 DSAFE=1]) the SQ
c890: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c Lite library wil
c8a0: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 l itself seriali
c8b0: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 ze access.** to
c8c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
c8d0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
c8e0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
c8f0: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 so that the.**
c900: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 application is f
c910: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 ree to use the s
c920: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
c930: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 nnection] or the
c940: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 .** same [prepar
c950: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
c960: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
c970: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ds at the same t
c980: 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 ime..** ^If SQLi
c990: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
c9a0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
c9b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
c9c0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
c9d0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
c9e0: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
c9f0: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
ca00: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 ble to set the S
ca10: 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
ca20: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a ding mode] and.*
ca30: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
ca40: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
ca50: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
ca60: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
ca70: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e he.** SQLITE_CON
ca80: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 FIG_SERIALIZED c
ca90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
caa0: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
cab0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
cac0: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a G_MALLOC</dt>.**
cad0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 <dd> ^(This opt
cae0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
caf0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
cb00: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
cb10: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
cb20: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
cb30: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
cb40: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 ructure. The ar
cb50: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
cb60: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 .** alternative
cb70: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
cb80: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
cb90: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
cba0: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 in place of.** t
cbb0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
cbc0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 tion routines bu
cbd0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
cbe0: 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 )^ ^SQLite makes
cbf0: 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 .** its own priv
cc00: 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
cc10: 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b content of the [
cc20: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
cc30: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a ods] structure.*
cc40: 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 * before the [sq
cc50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
cc60: 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 call returns.</d
cc70: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
cc80: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
cc90: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LLOC</dt>.** <dd
cca0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
ccb0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
ccc0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
ccd0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
cce0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
ccf0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
cd00: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
cd10: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ure. The [sqlit
cd20: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a e3_mem_methods].
cd30: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 ** structure is
cd40: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 filled with the
cd50: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 currently define
cd60: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 d memory allocat
cd70: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a ion routines.)^.
cd80: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 ** This option c
cd90: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 an be used to ov
cda0: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 erload the defau
cdb0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
cdc0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 tion.** routines
cdd0: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 with a wrapper
cde0: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 that simulations
cdf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
ce00: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a on failure or.**
ce10: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 tracks memory u
ce20: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c sage, for exampl
ce30: 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c e. </dd>.**.** <
ce40: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
ce50: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a _MEMSTATUS</dt>.
ce60: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
ce70: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c tion takes singl
ce80: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 e argument of ty
ce90: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 pe int, interpre
cea0: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f ted as a .** boo
ceb0: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 lean, which enab
cec0: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
ced0: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f the collection o
cee0: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 f memory allocat
cef0: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 ion .** statisti
cf00: 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 cs. ^(When memor
cf10: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
cf20: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 tistics are disa
cf30: 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f bled, the .** fo
cf40: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 llowing SQLite i
cf50: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 nterfaces become
cf60: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c non-operational
cf70: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 :.** <ul>.**
cf80: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
cf90: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a emory_used()].**
cfa0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
cfb0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
cfc0: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b r()].** <li> [
cfd0: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
cfe0: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 p_limit()].**
cff0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 <li> [sqlite3_st
d000: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 atus()].** </u
d010: 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 l>)^.** ^Memory
d020: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
d030: 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 stics are enable
d040: 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c d by default unl
d050: 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a ess SQLite is.**
d060: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
d070: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d SQLITE_DEFAULT_M
d080: 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 EMSTATUS]=0 in w
d090: 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 hich case memory
d0a0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 .** allocation s
d0b0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 tatistics are di
d0c0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
d0d0: 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a t..** </dd>.**.*
d0e0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
d0f0: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e FIG_SCRATCH</dt>
d100: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
d110: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
d120: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
d130: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 buffer that SQLi
d140: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a te can use for.*
d150: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 * scratch memory
d160: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 . There are thr
d170: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 ee arguments: A
d180: 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 pointer an 8-by
d190: 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 te.** aligned me
d1a0: 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d mory buffer from
d1b0: 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 63 which the scrac
d1c0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 h allocations wi
d1d0: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 ll be.** drawn,
d1e0: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
d1f0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
d200: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 ion (sz),.** and
d210: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
d220: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 ber of scratch a
d230: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 llocations (N).
d240: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d The sz.** argum
d250: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 ent must be a mu
d260: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 ltiple of 16. Th
d270: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 e sz parameter s
d280: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 hould be a few b
d290: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 ytes.** larger t
d2a0: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 han the actual s
d2b0: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71 cratch space req
d2c0: 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e 74 uired due to int
d2d0: 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a ernal overhead..
d2e0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
d2f0: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 ument must be a
d300: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d pointer to an 8-
d310: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 byte aligned buf
d320: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 fer.** of at lea
d330: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 st sz*N bytes of
d340: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c memory..** ^SQL
d350: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 ite will use no
d360: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 more than one sc
d370: 72 61 74 63 68 20 62 75 66 66 65 72 20 70 65 72 ratch buffer per
d380: 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 thread. So.**
d390: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 N should be set
d3a0: 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20 to the expected
d3b0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
d3c0: 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53 51 4c f threads. ^SQL
d3d0: 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 ite will.** neve
d3e0: 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 r require a scra
d3f0: 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 tch buffer that
d400: 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 20 74 is more than 6 t
d410: 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 imes the databas
d420: 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65 2e 20 e.** page size.
d430: 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 ^If SQLite needs
d440: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 needs additiona
d450: 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 l scratch memory
d460: 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74 beyond .** what
d470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
d480: 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 this configurati
d490: 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 on option, then
d4a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
d4b0: 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 loc()] will be u
d4c0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 sed to obtain th
d4d0: 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e e memory needed.
d4e0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
d4f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
d500: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 GECACHE</dt>.**
d510: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
d520: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
d530: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
d540: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 er that SQLite c
d550: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 an use for.** th
d560: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 e database page
d570: 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 cache with the d
d580: 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 efault page cach
d590: 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e e implemenation.
d5a0: 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 .** This confi
d5b0: 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 guration should
d5c0: 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 not be used if a
d5d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
d5e0: 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 fine page.** cac
d5f0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
d600: 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e n is loaded usin
d610: 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e g the SQLITE_CON
d620: 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f FIG_PCACHE optio
d630: 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 n..** There are
d640: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 three arguments
d650: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 to this option:
d660: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 A pointer to 8-b
d670: 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d yte aligned.** m
d680: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 emory, the size
d690: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 of each page buf
d6a0: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 fer (sz), and th
d6b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
d6c0: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a s (N)..** The sz
d6d0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
d6e0: 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 be the size of
d6f0: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 the largest data
d700: 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 base page.** (a
d710: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 power of two bet
d720: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 ween 512 and 327
d730: 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 68) plus a littl
d740: 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 e extra for each
d750: 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e .** page header.
d760: 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 ^The page head
d770: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f er size is 20 to
d780: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 40 bytes depend
d790: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f ing on.** the ho
d7a0: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e st architecture.
d7b0: 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 ^It is harmles
d7c0: 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 s, apart from th
d7d0: 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c e wasted memory,
d7e0: 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 .** to make sz a
d7f0: 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 little too larg
d800: 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a e. The first.**
d810: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
d820: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c point to an all
d830: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 ocation of at le
d840: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
d850: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 f memory..** ^SQ
d860: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 Lite will use th
d870: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 e memory provide
d880: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 d by the first a
d890: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 rgument to satis
d8a0: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 fy its.** memory
d8b0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 needs for the f
d8c0: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 irst N pages tha
d8d0: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 t it adds to cac
d8e0: 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f he. ^If additio
d8f0: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 nal.** page cach
d900: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 e memory is need
d910: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 ed beyond what i
d920: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 s provided by th
d930: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a is option, then.
d940: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 ** SQLite goes t
d950: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
d960: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 c()] for the add
d970: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 itional storage
d980: 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 space..** ^The i
d990: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 mplementation mi
d9a0: 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d ght use one or m
d9b0: 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 ore of the N buf
d9c0: 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a fers to hold .**
d9d0: 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 memory accounti
d9e0: 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 ng information.
d9f0: 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 The pointer in t
da00: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
da10: 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 t must.** be ali
da20: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
da30: 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 e boundary or su
da40: 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f bsequent behavio
da50: 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 r of SQLite.** w
da60: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 ill be undefined
da70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
da80: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 >SQLITE_CONFIG_H
da90: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAP</dt>.** <dd>
daa0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 ^This option sp
dab0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
dac0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
dad0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
dae0: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f use.** for all o
daf0: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 f its dynamic me
db00: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
db10: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f needs beyond tho
db20: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 se provided.** f
db30: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f or by [SQLITE_CO
db40: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e NFIG_SCRATCH] an
db50: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 d [SQLITE_CONFIG
db60: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 _PAGECACHE]..**
db70: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
db80: 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d arguments: An 8-
db90: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 byte aligned poi
dba0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f nter to the memo
dbb0: 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 ry,.** the numbe
dbc0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
dbd0: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c e memory buffer,
dbe0: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d and the minimum
dbf0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
dc00: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 ..** ^If the fir
dc10: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 st pointer (the
dc20: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 memory pointer)
dc30: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 is NULL, then SQ
dc40: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 Lite reverts.**
dc50: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 to using its def
dc60: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ault memory allo
dc70: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 cator (the syste
dc80: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 m malloc() imple
dc90: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 mentation),.** u
dca0: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 ndoing any prior
dcb0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b invocation of [
dcc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
dcd0: 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a LLOC]. ^If the.
dce0: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 ** memory pointe
dcf0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e r is not NULL an
dd00: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 d either [SQLITE
dd10: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d _ENABLE_MEMSYS3]
dd20: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 or.** [SQLITE_E
dd30: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 NABLE_MEMSYS5] a
dd40: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e re defined, then
dd50: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 the alternative
dd60: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
dd70: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 ator is engaged
dd80: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 to handle all of
dd90: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 SQLites memory
dda0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
ddb0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 ..** The first p
ddc0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
ddd0: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 ry pointer) must
dde0: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
ddf0: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e n 8-byte.** boun
de00: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 dary or subseque
de10: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 nt behavior of S
de20: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e QLite will be un
de30: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
de40: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
de50: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e ONFIG_MUTEX</dt>
de60: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
de70: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
de80: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
de90: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
dea0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
deb0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
dec0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
ded0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
dee0: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 he argument spec
def0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 ifies.** alterna
df00: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
df10: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f utex routines to
df20: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 be used in plac
df30: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 e.** the mutex r
df40: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
df50: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 to SQLite.)^ ^S
df60: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
df70: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e py of the.** con
df80: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c tent of the [sql
df90: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
dfa0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 ds] structure be
dfb0: 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f fore the call to
dfc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
dfd0: 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 fig()] returns.
dfe0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
dff0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
e000: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
e010: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
e020: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
e030: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
e040: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 then.** the ent
e050: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 ire mutexing sub
e060: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 system is omitte
e070: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 d from the build
e080: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 and hence calls
e090: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
e0a0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 config()] with t
e0b0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
e0c0: 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 _MUTEX configura
e0d0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c tion option will
e0e0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
e0f0: 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a TE_ERROR].</dd>.
e100: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
e110: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
e120: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
e130: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
e140: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
e150: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
e160: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
e170: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
e180: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
e190: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
e1a0: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 e. The.** [sqli
e1b0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
e1c0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
e1d0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
e1e0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
e1f0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 ined mutex routi
e200: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f nes.)^.** This o
e210: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
e220: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 d to overload th
e230: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 e default mutex
e240: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f allocation.** ro
e250: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 utines with a wr
e260: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 apper used to tr
e270: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 ack mutex usage
e280: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a for performance.
e290: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 ** profiling or
e2a0: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 testing, for exa
e2b0: 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 mple. ^If SQLi
e2c0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
e2d0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
e2e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
e2f0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
e300: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
e310: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
e320: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 the entire mute
e330: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 xing subsystem i
e340: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 s omitted from t
e350: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e he build and hen
e360: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b ce calls to.** [
e370: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
e380: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 ] with the SQLIT
e390: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
e3a0: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 X configuration
e3b0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 option will.** r
e3c0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
e3d0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ROR].</dd>.**.**
e3e0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
e3f0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 IG_LOOKASIDE</dt
e400: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
e410: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 option takes tw
e420: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 o arguments that
e430: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 determine the d
e440: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 efault.** memory
e450: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 allocation for
e460: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 the lookaside me
e470: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f mory allocator o
e480: 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 n each.** [datab
e490: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
e4a0: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 The first argu
e4b0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
e4c0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
e4d0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
e4e0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 t and the second
e4f0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
e500: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 f.** slots alloc
e510: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 ated to each dat
e520: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
e530: 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 .)^ ^(This opti
e540: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c on sets the.** <
e550: 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f i>default</i> lo
e560: 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 okaside size. Th
e570: 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 e [SQLITE_DBCONF
e580: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a IG_LOOKASIDE].**
e590: 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 verb to [sqlite
e5a0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 3_db_config()] c
e5b0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 an be used to ch
e5c0: 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 ange the lookasi
e5d0: 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 de.** configurat
e5e0: 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 ion on individua
e5f0: 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e l connections.)^
e600: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
e610: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
e620: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 CACHE</dt>.** <d
e630: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
e640: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
e650: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
e660: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a s a pointer to.*
e670: 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 * an [sqlite3_pc
e680: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 ache_methods] ob
e690: 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 ject. This obje
e6a0: 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 ct specifies the
e6b0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f interface.** to
e6c0: 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 a custom page c
e6d0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
e6e0: 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 ion.)^ ^SQLite
e6f0: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
e700: 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e the.** object an
e710: 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 d uses it for pa
e720: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 ge cache memory
e730: 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 allocations.</dd
e740: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
e750: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
e760: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
e770: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
e780: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
e790: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
e7a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
e7b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 ** [sqlite3_pcac
e7c0: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 he_methods] obje
e7d0: 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 ct. SQLite copi
e7e0: 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e es of the curren
e7f0: 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 t.** page cache
e800: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
e810: 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e nto that object.
e820: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c )^ </dd>.**.** <
e830: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
e840: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
e850: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f NGLETHREAD 1 /
e860: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
e870: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
e880: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 ULTITHREAD 2
e890: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
e8a0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
e8b0: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 SERIALIZED 3
e8c0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
e8d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
e8e0: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 _MALLOC 4
e8f0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
e900: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
e910: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
e920: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 IG_GETMALLOC
e930: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 5 /* sqlite3_m
e940: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
e950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
e960: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 NFIG_SCRATCH
e970: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 6 /* void*,
e980: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f int sz, int N */
e990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e9a0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
e9b0: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 7 /* void*
e9c0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
e9d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
e9e0: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 E_CONFIG_HEAP
e9f0: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 8 /* voi
ea00: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 d*, int nByte, i
ea10: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e nt min */.#defin
ea20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
ea30: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 MEMSTATUS 9
ea40: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 /* boolean */.#
ea50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
ea60: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 NFIG_MUTEX
ea70: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 10 /* sqlite3
ea80: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
ea90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
eaa0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
eab0: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c X 11 /* sql
eac0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
ead0: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f ds* */./* previo
eae0: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 usly SQLITE_CONF
eaf0: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 IG_CHUNKALLOC 12
eb00: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e which is now un
eb10: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e used. */ .#defin
eb20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
eb30: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 LOOKASIDE 13
eb40: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 /* int int */.#
eb50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
eb60: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 NFIG_PCACHE
eb70: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 14 /* sqlite3
eb80: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a _pcache_methods*
eb90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
eba0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
ebb0: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 CHE 15 /* sq
ebc0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
ebd0: 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 hods* */../*.**
ebe0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
ebf0: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
ec00: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
ec10: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
ec20: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
ec30: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
ec40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
ec50: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
ec60: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
ec70: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
ec80: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
ec90: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
eca0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
ecb0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
ecc0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
ecd0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
ece0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
ecf0: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
ed00: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
ed10: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
ed20: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
ed30: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
ed40: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
ed50: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
ed60: 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f m [sqlite3_db_co
ed70: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
ed80: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
ed90: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e call worked. ^
eda0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f The [sqlite3_db_
edb0: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
edc0: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
edd0: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
ede0: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
edf0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
ee00: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
ee10: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
ee20: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
ee30: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
ee40: 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
ee50: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
ee60: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
ee70: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 ption takes thre
ee80: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 e additional arg
ee90: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
eea0: 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c rmine the .** [l
eeb0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
eec0: 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 allocator] confi
eed0: 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 guration for the
eee0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
eef0: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 ction]..** ^The
ef00: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 first argument (
ef10: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
ef20: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
ef30: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 db_config()] is
ef40: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
ef50: 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 an memory buffer
ef60: 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b to use for look
ef70: 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a aside memory..**
ef80: 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
ef90: 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 ment after the S
efa0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
efb0: 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a OOKASIDE verb.**
efc0: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 may be NULL in
efd0: 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 which case SQLit
efe0: 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 e will allocate
eff0: 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 the.** lookaside
f000: 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 buffer itself u
f010: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 sing [sqlite3_ma
f020: 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 lloc()]. ^The se
f030: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
f040: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 the.** size of
f050: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 each lookaside b
f060: 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 uffer slot. ^Th
f070: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
f080: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
f090: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 f.** slots. The
f0a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
f0b0: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 fer in the first
f0c0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 argument must b
f0d0: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a e greater than.*
f0e0: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 * or equal to th
f0f0: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 e product of the
f100: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 second and thir
f110: 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 d arguments. Th
f120: 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 e buffer.** must
f130: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
f140: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 n 8-byte boundar
f150: 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f y. ^If the seco
f160: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
f170: 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 * SQLITE_DBCONFI
f180: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e G_LOOKASIDE is n
f190: 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 ot a multiple of
f1a0: 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 8, it is intern
f1b0: 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 ally.** rounded
f1c0: 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 down to the next
f1d0: 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 smaller.** mult
f1e0: 69 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20 iple of 8. See
f1f0: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f also: [SQLITE_CO
f200: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c NFIG_LOOKASIDE]<
f210: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
f220: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
f230: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
f240: 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f ASIDE 1001 /
f250: 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 * void* int int
f260: 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */.../*.** CAPI3
f270: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
f280: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 isable Extended
f290: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a Result Codes.**.
f2a0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
f2b0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f extended_result_
f2c0: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 codes() routine
f2d0: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
f2e0: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 les the.** [exte
f2f0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
f300: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 s] feature of SQ
f310: 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e Lite. ^The exten
f320: 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ded result.** co
f330: 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 des are disabled
f340: 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 by default for
f350: 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 historical compa
f360: 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 tibility..*/.int
f370: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
f380: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 d_result_codes(s
f390: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f qlite3*, int ono
f3a0: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ff);../*.** CAPI
f3b0: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 3REF: Last Inser
f3c0: 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 t Rowid.**.** ^E
f3d0: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 ach entry in an
f3e0: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 SQLite table has
f3f0: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 a unique 64-bit
f400: 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 signed.** integ
f410: 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 er key called th
f420: 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 e [ROWID | "rowi
f430: 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 d"]. ^The rowid
f440: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 is always availa
f450: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 ble.** as an und
f460: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e eclared column n
f470: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c amed ROWID, OID,
f480: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c or _ROWID_ as l
f490: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 ong as those.**
f4a0: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c names are not al
f4b0: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 so used by expli
f4c0: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 citly declared c
f4d0: 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 olumns. ^If.** t
f4e0: 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 he table has a c
f4f0: 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 olumn of type [I
f500: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
f510: 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f EY] then that co
f520: 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 lumn.** is anoth
f530: 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 er alias for the
f540: 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 rowid..**.** ^T
f550: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
f560: 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 rns the [rowid]
f570: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 of the most rece
f580: 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c nt.** successful
f590: 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 [INSERT] into t
f5a0: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d he database from
f5b0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
f5c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e onnection].** in
f5d0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
f5e0: 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20 73 75 63 ent. ^If no suc
f5f0: 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
f600: 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
f610: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 ccurred on that
f620: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
f630: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 ion, zero is ret
f640: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 urned..**.** ^(I
f650: 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 f an [INSERT] oc
f660: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 curs within a tr
f670: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 igger, then the
f680: 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 [rowid] of the i
f690: 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 nserted.** row i
f6a0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
f6b0: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f is routine as lo
f6c0: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 ng as the trigge
f6d0: 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a r is running..**
f6e0: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 But once the tr
f6f0: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 igger terminates
f700: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 , the value retu
f710: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 rned by this rou
f720: 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 tine.** reverts
f730: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 to the last valu
f740: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 e inserted befor
f750: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69 e the trigger fi
f760: 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e red.)^.**.** ^An
f770: 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 [INSERT] that f
f780: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f ails due to a co
f790: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
f7a0: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 on is not a.** s
f7b0: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
f7c0: 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 T] and does not
f7d0: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
f7e0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
f7f0: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e s.** routine. ^
f800: 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 Thus INSERT OR F
f810: 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 AIL, INSERT OR I
f820: 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 GNORE, INSERT OR
f830: 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e ROLLBACK,.** an
f840: 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 d INSERT OR ABOR
f850: 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 T make no change
f860: 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 s to the return
f870: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a value of this.**
f880: 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 routine when th
f890: 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 eir insertion fa
f8a0: 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 ils. ^(When INS
f8b0: 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a ERT OR REPLACE.*
f8c0: 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 * encounters a c
f8d0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
f8e0: 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 ion, it does not
f8f0: 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 fail. The.** I
f900: 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 NSERT continues
f910: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 to completion af
f920: 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 ter deleting row
f930: 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a s that caused.**
f940: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 the constraint
f950: 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 problem so INSER
f960: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c T OR REPLACE wil
f970: 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a l always change.
f980: 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ** the return va
f990: 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 lue of this inte
f9a0: 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e rface.)^.**.** ^
f9b0: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 For the purposes
f9c0: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
f9d0: 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 , an [INSERT] is
f9e0: 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a considered to.*
f9f0: 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 * be successful
fa00: 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 even if it is su
fa10: 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 bsequently rolle
fa20: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
fa30: 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 is function is a
fa40: 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c ccessible to SQL
fa50: 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 statements via
fa60: 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 the.** [last_ins
fa70: 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 ert_rowid() SQL
fa80: 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
fa90: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
faa0: 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 hread performs a
fab0: 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e new [INSERT] on
fac0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 the same.** dat
fad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
fae0: 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 while the [sqli
faf0: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
fb00: 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 rowid()].** func
fb10: 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 tion is running
fb20: 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 and thus changes
fb30: 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 the last insert
fb40: 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 [rowid],.** the
fb50: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
fb60: 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
fb70: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
fb80: 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 id()] is.** unpr
fb90: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 edictable and mi
fba0: 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 ght not equal ei
fbb0: 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 ther the old or
fbc0: 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 the new.** last
fbd0: 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a insert [rowid]..
fbe0: 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 */.sqlite3_int64
fbf0: 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
fc00: 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 sert_rowid(sqlit
fc10: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
fc20: 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 I3REF: Count The
fc30: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
fc40: 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e Modified.**.** ^
fc50: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
fc60: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
fc70: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 of database row
fc80: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e s that were chan
fc90: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 ged.** or insert
fca0: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 ed or deleted by
fcb0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
fcc0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c ly completed SQL
fcd0: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e statement.** on
fce0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
fcf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
fd00: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 fied by the firs
fd10: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 t parameter..**
fd20: 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 ^(Only changes t
fd30: 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 hat are directly
fd40: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
fd50: 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 e [INSERT], [UPD
fd60: 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c ATE],.** or [DEL
fd70: 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 ETE] statement a
fd80: 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 re counted. Aux
fd90: 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 iliary changes c
fda0: 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 aused by.** trig
fdb0: 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e gers or [foreign
fdc0: 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 key actions] ar
fdd0: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e e not counted.)^
fde0: 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c Use the.** [sql
fdf0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
fe00: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 es()] function t
fe10: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c o find the total
fe20: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 number of chang
fe30: 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 es.** including
fe40: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
fe50: 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 y triggers and f
fe60: 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
fe70: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 ns..**.** ^Chang
fe80: 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 es to a view tha
fe90: 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 t are simulated
fea0: 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f by an [INSTEAD O
feb0: 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 F trigger].** ar
fec0: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 e not counted.
fed0: 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 Only real table
fee0: 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e changes are coun
fef0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 ted..**.** ^(A "
ff00: 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 row change" is a
ff10: 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e change to a sin
ff20: 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e gle row of a sin
ff30: 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 gle table.** cau
ff40: 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 sed by an INSERT
ff50: 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 , DELETE, or UPD
ff60: 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 ATE statement.
ff70: 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 Rows that.** are
ff80: 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 changed as side
ff90: 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 effects of [REP
ffa0: 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 LACE] constraint
ffb0: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 resolution,.**
ffc0: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 rollback, ABORT
ffd0: 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f processing, [DRO
ffe0: 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 P TABLE], or by
fff0: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 any other.** mec
10000 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 hanisms do not c
10010 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 ount as direct r
10020 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a ow changes.)^.**
10030 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 .** A "trigger c
10040 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f ontext" is a sco
10050 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 pe of execution
10060 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a that begins and.
10070 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 ** ends with the
10080 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 script of a [CR
10090 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
100a0 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 rigger]. .** Mos
100b0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 t SQL statements
100c0 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 are.** evaluate
100d0 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 d outside of any
100e0 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 trigger. This
100f0 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 is the "top leve
10100 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f l".** trigger co
10110 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 ntext. If a tri
10120 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 gger fires from
10130 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 the top level, a
10140 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 .** new trigger
10150 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 context is enter
10160 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 ed for the durat
10170 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a ion of that one.
10180 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 ** trigger. Sub
10190 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 triggers create
101a0 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 subcontexts for
101b0 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a their duration..
101c0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b **.** ^Calling [
101d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
101e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 or [sqlite3_step
101f0 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 ()] recursively
10200 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 does.** not crea
10210 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 te a new trigger
10220 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
10230 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 ^This function r
10240 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
10250 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 r of direct row
10260 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a changes in the.*
10270 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e * most recent IN
10280 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
10290 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
102a0 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d t within the sam
102b0 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e e.** trigger con
102c0 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 text..**.** ^Thu
102d0 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 s, when called f
102e0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 rom the top leve
102f0 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e l, this function
10300 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 returns the.**
10310 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 number of change
10320 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 s in the most re
10330 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 cent INSERT, UPD
10340 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
10350 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 * that also occu
10360 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 rred at the top
10370 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e level. ^(Within
10380 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 the body of a t
10390 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 rigger,.** the s
103a0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
103b0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
103c0 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 e called to find
103d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
103e0 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 * changes in the
103f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 most recently c
10400 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c ompleted INSERT,
10410 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
10420 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 TE.** statement
10430 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 within the body
10440 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 of the same trig
10450 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ger..** However,
10460 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 the number retu
10470 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e rned does not in
10480 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a clude changes.**
10490 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 caused by subtr
104a0 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f iggers since tho
104b0 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 se have their ow
104c0 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a n context.)^.**.
104d0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 ** See also the
104e0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
104f0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 hanges()] interf
10500 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 ace, the.** [cou
10510 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d nt_changes pragm
10520 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 a], and the [cha
10530 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 nges() SQL funct
10540 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 ion]..**.** If a
10550 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
10560 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f makes changes o
10570 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 n the same datab
10580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
10590 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 * while [sqlite3
105a0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 _changes()] is r
105b0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 unning then the
105c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a value returned.*
105d0 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 * is unpredictab
105e0 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 le and not meani
105f0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ngful..*/.int sq
10600 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 lite3_changes(sq
10610 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
10620 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 CAPI3REF: Total
10630 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d Number Of Rows M
10640 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 odified.**.** ^T
10650 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
10660 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
10670 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 of row changes c
10680 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 aused by [INSERT
10690 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f ],.** [UPDATE] o
106a0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
106b0 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 ments since the
106c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
106d0 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 tion] was opened
106e0 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 ..** ^(The count
106f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
10700 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
10710 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c es() includes al
10720 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f l changes.** fro
10730 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 m all [CREATE TR
10740 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d IGGER | trigger]
10750 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 contexts and ch
10760 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a anges made by.**
10770 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 [foreign key ac
10780 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c tions]. However,
10790 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f .** the count do
107a0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 es not include c
107b0 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 hanges used to i
107c0 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 mplement [REPLAC
107d0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a E] constraints,.
107e0 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 ** do rollbacks
107f0 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 or ABORT process
10800 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 ing, or [DROP TA
10810 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e BLE] processing.
10820 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 The.** count d
10830 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
10840 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 rows of views th
10850 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 at fire an [INST
10860 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c EAD OF trigger],
10870 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 .** though if th
10880 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 e INSTEAD OF tri
10890 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 gger makes chang
108a0 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 es of its own, t
108b0 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a hose changes .**
108c0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a are counted.)^.
108d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
108e0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 total_changes()
108f0 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 function counts
10900 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 the changes as s
10910 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 oon as.** the st
10920 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b atement that mak
10930 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c es them is compl
10940 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 eted (when the s
10950 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a tatement handle.
10960 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 ** is passed to
10970 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
10980 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 ] or [sqlite3_fi
10990 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a nalize()])..**.*
109a0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b * See also the [
109b0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
109c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 )] interface, th
109d0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e e.** [count_chan
109e0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 ges pragma], and
109f0 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e the [total_chan
10a00 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 ges() SQL functi
10a10 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 on]..**.** If a
10a20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
10a30 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e makes changes on
10a40 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
10a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
10a60 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
10a70 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
10a80 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
10a90 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 the value.** re
10aa0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 turned is unpred
10ab0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
10ac0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
10ad0 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c nt sqlite3_total
10ae0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
10af0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
10b00 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 REF: Interrupt A
10b10 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 Long-Running Qu
10b20 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ery.**.** ^This
10b30 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 function causes
10b40 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 any pending data
10b50 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 base operation t
10b60 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 o abort and.** r
10b70 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 eturn at its ear
10b80 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 liest opportunit
10b90 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 y. This routine
10ba0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 is typically.**
10bb0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e called in respon
10bc0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 se to a user act
10bd0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 ion such as pres
10be0 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a sing "Cancel".**
10bf0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 or Ctrl-C where
10c00 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 the user wants
10c10 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 a long query ope
10c20 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a ration to halt.*
10c30 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a * immediately..*
10c40 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 *.** ^It is safe
10c50 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f to call this ro
10c60 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 utine from a thr
10c70 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 ead different fr
10c80 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 om the.** thread
10c90 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 that is current
10ca0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 ly running the d
10cb0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
10cc0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 n. But it.** is
10cd0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c not safe to cal
10ce0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 l this routine w
10cf0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
10d00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
10d10 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 .** is closed or
10d20 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 might close bef
10d30 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 ore sqlite3_inte
10d40 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e rrupt() returns.
10d50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 .**.** ^If an SQ
10d60 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 L operation is v
10d70 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 ery nearly finis
10d80 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 hed at the time
10d90 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f when.** sqlite3_
10da0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 interrupt() is c
10db0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d alled, then it m
10dc0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e ight not have an
10dd0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 opportunity.**
10de0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 to be interrupte
10df0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 d and might cont
10e00 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 inue to completi
10e10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 on..**.** ^An SQ
10e20 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 L operation that
10e30 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 is interrupted
10e40 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c will return [SQL
10e50 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a ITE_INTERRUPT]..
10e60 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 ** ^If the inter
10e70 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 rupted SQL opera
10e80 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 tion is an INSER
10e90 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
10ea0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 LETE.** that is
10eb0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 inside an explic
10ec0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
10ed0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 then the entire
10ee0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 transaction.** w
10ef0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ill be rolled ba
10f00 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
10f10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
10f20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
10f30 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 D) call is in ef
10f40 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 fect until all c
10f50 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 urrently running
10f60 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
10f70 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 ts on [database
10f80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f connection] D co
10f90 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 6e 65 77 mplete. Any new
10fa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
10fb0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
10fc0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 ted after the sq
10fd0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
10fe0 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 ) call and befor
10ff0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e e the .** runnin
11000 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 g statements rea
11010 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e ches zero are in
11020 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 terrupted as if
11030 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a they had been.**
11040 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 running prior t
11050 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e o the sqlite3_in
11060 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 terrupt() call.
11070 20 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 New SQL stateme
11080 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
11090 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
110a0 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d e running statem
110b0 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 ent count reache
110c0 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f s zero are.** no
110d0 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 t effected by th
110e0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
110f0 75 70 74 28 29 2e 29 5e 0a 2a 2a 20 5e 41 20 63 upt().)^.** ^A c
11100 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 all to sqlite3_i
11110 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 nterrupt(D) that
11120 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 occurs when the
11130 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e re are no runnin
11140 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 g.** SQL stateme
11150 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 nts is a no-op a
11160 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 nd has no effect
11170 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e on SQL statemen
11180 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
11190 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
111a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
111b0 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e pt() call return
111c0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 s..**.** If the
111d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
111e0 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 ion closes while
111f0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 [sqlite3_interr
11200 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e upt()].** is run
11210 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 ning then bad th
11220 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 ings will likely
11230 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 happen..*/.void
11240 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
11250 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f pt(sqlite3*);../
11260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
11270 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 etermine If An S
11280 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 QL Statement Is
11290 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 Complete.**.** T
112a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
112b0 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 e useful during
112c0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 command-line inp
112d0 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ut to determine
112e0 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e if the.** curren
112f0 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 tly entered text
11300 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 seems to form a
11310 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 complete SQL st
11320 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 atement or.** if
11330 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 additional inpu
11340 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f t is needed befo
11350 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 re sending the t
11360 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 ext into.** SQLi
11370 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 te for parsing.
11380 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
11390 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 return 1 if the
113a0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a input string.**
113b0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 appears to be a
113c0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 complete SQL st
113d0 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 atement. ^A sta
113e0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 tement is judged
113f0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 to be.** comple
11400 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 te if it ends wi
11410 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 th a semicolon t
11420 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 oken and is not
11430 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a a prefix of a.**
11440 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 well-formed CRE
11450 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 ATE TRIGGER stat
11460 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c ement. ^Semicol
11470 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 ons that are emb
11480 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 edded within.**
11490 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 string literals
114a0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 or quoted identi
114b0 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f fier names or co
114c0 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a mments are not.*
114d0 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f * independent to
114e0 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 kens (they are p
114f0 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e art of the token
11500 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 in which they a
11510 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 re.** embedded)
11520 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 and thus do not
11530 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 count as a state
11540 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e ment terminator.
11550 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a ^Whitespace.**
11560 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 and comments th
11570 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 at follow the fi
11580 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 nal semicolon ar
11590 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a e ignored..**.**
115a0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
115b0 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 return 0 if the
115c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e statement is in
115d0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 complete. ^If a
115e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
115f0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 ation fails, the
11600 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 n SQLITE_NOMEM i
11610 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
11620 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
11630 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 s do not parse t
11640 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
11650 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e s thus.** will n
11660 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 ot detect syntac
11670 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 tically incorrec
11680 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 t SQL..**.** ^(I
11690 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 f SQLite has not
116a0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 been initialize
116b0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
116c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 _initialize()] p
116d0 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f rior .** to invo
116e0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d king sqlite3_com
116f0 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 plete16() then s
11700 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
11710 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
11720 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
11730 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c by sqlite3_compl
11740 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 ete16(). If tha
11750 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e t initialization
11760 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 fails,.** then
11770 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
11780 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f from sqlite3_co
11790 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 mplete16() will
117a0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 be non-zero.** r
117b0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
117c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
117d0 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d input SQL is com
117e0 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 plete.)^.**.** T
117f0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c he input to [sql
11800 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d ite3_complete()]
11810 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d must be a zero-
11820 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 terminated.** UT
11830 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a F-8 string..**.*
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 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 16()] must be a
11870 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
11880 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
11890 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 in native byte
118a0 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 order..*/.int sq
118b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 lite3_complete(c
118c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b onst char *sql);
118d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d .int sqlite3_com
118e0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f plete16(const vo
118f0 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a id *sql);../*.**
11900 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 CAPI3REF: Regis
11910 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 ter A Callback T
11920 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f o Handle SQLITE_
11930 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a BUSY Errors.**.*
11940 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
11950 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 sets a callback
11960 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 function that mi
11970 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ght be invoked w
11980 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 henever.** an at
11990 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f tempt is made to
119a0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 open a database
119b0 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 table that anot
119c0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 her thread.** or
119d0 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 process has loc
119e0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ked..**.** ^If t
119f0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
11a00 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b is NULL, then [
11a10 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 SQLITE_BUSY] or
11a20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
11a30 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 OCKED].** is ret
11a40 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
11a50 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 y upon encounter
11a60 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e ing the lock. ^
11a70 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
11a80 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e back.** is not N
11a90 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 ULL, then the ca
11aa0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 llback might be
11ab0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f invoked with two
11ac0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a arguments..**.*
11ad0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
11ae0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 ument to the bus
11af0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 y handler is a c
11b00 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a opy of the void*
11b10 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a pointer which.*
11b20 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 * is the third a
11b30 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
11b40 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
11b50 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 ). ^The second
11b60 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 argument to.** t
11b70 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
11b80 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
11b90 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
11ba0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 that the busy ha
11bb0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 ndler has.** bee
11bc0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 n invoked for th
11bd0 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 is locking event
11be0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 . ^If the.** bu
11bf0 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 sy callback retu
11c00 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 rns 0, then no a
11c10 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 dditional attemp
11c20 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a ts are made to.*
11c30 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 * access the dat
11c40 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 abase and [SQLIT
11c50 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 E_BUSY] or [SQLI
11c60 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
11c70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
11c80 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 * ^If the callba
11c90 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
11ca0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 ero, then anothe
11cb0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 r attempt.** is
11cc0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 made to open the
11cd0 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 database for re
11ce0 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 ading and the cy
11cf0 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a cle repeats..**.
11d00 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 ** The presence
11d10 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 of a busy handle
11d20 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 r does not guara
11d30 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c ntee that it wil
11d40 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 l be invoked.**
11d50 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f when there is lo
11d60 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e ck contention. ^
11d70 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d If SQLite determ
11d80 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 ines that invoki
11d90 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 ng the busy.** h
11da0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 andler could res
11db0 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 ult in a deadloc
11dc0 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 k, it will go ah
11dd0 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b ead and return [
11de0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 SQLITE_BUSY].**
11df0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
11e00 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 _BLOCKED] instea
11e10 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 d of invoking th
11e20 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
11e30 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 ** Consider a sc
11e40 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 enario where one
11e50 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
11e60 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 ing a read lock
11e70 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 that.** it is tr
11e80 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 ying to promote
11e90 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f to a reserved lo
11ea0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f ck and.** a seco
11eb0 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f nd process is ho
11ec0 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 lding a reserved
11ed0 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 lock that it is
11ee0 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 trying.** to pr
11ef0 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c omote to an excl
11f00 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 usive lock. The
11f10 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 first process c
11f20 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a annot proceed.**
11f30 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 because it is b
11f40 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 locked by the se
11f50 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 cond and the sec
11f60 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e ond process cann
11f70 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 ot.** proceed be
11f80 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 cause it is bloc
11f90 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ked by the first
11fa0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 . If both proce
11fb0 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 sses.** invoke t
11fc0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 he busy handlers
11fd0 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d , neither will m
11fe0 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 ake any progress
11ff0 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a . Therefore,.**
12000 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 SQLite returns
12010 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f [SQLITE_BUSY] fo
12020 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 r the first proc
12030 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 ess, hoping that
12040 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e this.** will in
12050 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 duce the first p
12060 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 rocess to releas
12070 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 e its read lock
12080 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 and allow.** the
12090 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
120a0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a to proceed..**.*
120b0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 * ^The default b
120c0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 usy callback is
120d0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
120e0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 [SQLITE_BUSY] e
120f0 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 rror is converte
12100 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 d to [SQLITE_IOE
12110 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 RR_BLOCKED].** w
12120 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e hen SQLite is in
12130 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 the middle of a
12140 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 large transacti
12150 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 on where all the
12160 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c .** changes will
12170 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 not fit into th
12180 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 e in-memory cach
12190 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a e. SQLite will.
121a0 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 ** already hold
121b0 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 a RESERVED lock
121c0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 on the database
121d0 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 file, but it nee
121e0 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 ds.** to promote
121f0 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 this lock to EX
12200 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 CLUSIVE so that
12210 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 it can spill cac
12220 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f he.** pages into
12230 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
12240 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 le without harm
12250 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a to concurrent.**
12260 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 readers. ^If i
12270 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 t is unable to p
12280 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c romote the lock,
12290 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d then the in-mem
122a0 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c ory.** cache wil
122b0 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 l be left in an
122c0 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 inconsistent sta
122d0 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 te and so the er
122e0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 ror.** code is p
122f0 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 romoted from the
12300 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 relatively beni
12310 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d gn [SQLITE_BUSY]
12320 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 to.** the more
12330 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 severe [SQLITE_I
12340 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 OERR_BLOCKED].
12350 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 ^This error code
12360 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f promotion.** fo
12370 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 rces an automati
12380 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 c rollback of th
12390 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 e changes. See
123a0 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 the.** <a href="
123b0 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d /cvstrac/wiki?p=
123c0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 CorruptionFollow
123d0 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a ingBusyError">.*
123e0 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c * CorruptionFoll
123f0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f owingBusyError</
12400 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 a> wiki page for
12410 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 a discussion of
12420 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 why.** this is
12430 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a important..**.**
12440 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ^(There can onl
12450 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
12460 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e sy handler defin
12470 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b ed for each.** [
12480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12490 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 ion]. Setting a
124a0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 new busy handle
124b0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 r clears any.**
124c0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 previously set h
124d0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 andler.)^ ^Note
124e0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 that calling [s
124f0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
12500 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 out()].** will a
12510 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 lso set or clear
12520 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
12530 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 r..**.** The bus
12540 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c y callback shoul
12550 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 d not take any a
12560 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 ctions which mod
12570 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 ify the.** datab
12580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
12590 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
125a0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 busy handler. A
125b0 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a ny such actions.
125c0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 ** result in und
125d0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e efined behavior.
125e0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 .** .** A busy h
125f0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 andler must not
12600 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
12610 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
12620 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 or [prepared st
12630 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e atement] that in
12640 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
12650 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 andler..*/.int s
12660 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
12670 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e ler(sqlite3*, in
12680 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c t(*)(void*,int),
12690 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
126a0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 CAPI3REF: Set A
126b0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a Busy Timeout.**.
126c0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
126d0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 sets a [sqlite3
126e0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 _busy_handler |
126f0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 busy handler] th
12700 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 at sleeps.** for
12710 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f a specified amo
12720 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e unt of time when
12730 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b a table is lock
12740 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 ed. ^The handle
12750 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 r.** will sleep
12760 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 multiple times u
12770 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d ntil at least "m
12780 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
12790 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 of sleeping.** h
127a0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e ave accumulated.
127b0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 ^After at leas
127c0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
127d0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c nds of sleeping,
127e0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 .** the handler
127f0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 returns 0 which
12800 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f causes [sqlite3_
12810 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 step()] to retur
12820 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 n.** [SQLITE_BUS
12830 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f Y] or [SQLITE_IO
12840 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a ERR_BLOCKED]..**
12850 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 .** ^Calling thi
12860 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
12870 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 n argument less
12880 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
12890 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f zero.** turns o
128a0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 ff all busy hand
128b0 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 lers..**.** ^(Th
128c0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
128d0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
128e0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
128f0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
12900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
12910 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f any any given mo
12920 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 ment. If anothe
12930 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a r busy handler.*
12940 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 * was defined (
12950 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
12960 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 usy_handler()])
12970 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
12980 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
12990 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 , that other bus
129a0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 y handler is cle
129b0 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 ared.)^.*/.int s
129c0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
129d0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e out(sqlite3*, in
129e0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 t ms);../*.** CA
129f0 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 PI3REF: Convenie
12a00 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 nce Routines For
12a10 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 Running Queries
12a20 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f .**.** Definitio
12a30 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 n: A <b>result t
12a40 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f able</b> is memo
12a50 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ry data structur
12a60 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 e created by the
12a70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 .** [sqlite3_get
12a80 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 _table()] interf
12a90 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 ace. A result t
12aa0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 able records the
12ab0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 .** complete que
12ac0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 ry results from
12ad0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 one or more quer
12ae0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ies..**.** The t
12af0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c able conceptuall
12b00 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f y has a number o
12b10 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d f rows and colum
12b20 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 ns. But.** thes
12b30 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f e numbers are no
12b40 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 t part of the re
12b50 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c sult table itsel
12b60 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d f. These.** num
12b70 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 bers are obtaine
12b80 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c d separately. L
12b90 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 et N be the numb
12ba0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e er of rows.** an
12bb0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 d M be the numbe
12bc0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a r of columns..**
12bd0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
12be0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f le is an array o
12bf0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 f pointers to ze
12c00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
12c10 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 F-8 strings..**
12c20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a There are (N+1)*
12c30 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 M elements in th
12c40 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 e array. The fi
12c50 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 rst M pointers p
12c60 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d oint.** to zero-
12c70 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
12c80 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e gs that contain
12c90 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 the names of th
12ca0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 e columns..** Th
12cb0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 e remaining entr
12cc0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f ies all point to
12cd0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 query results.
12ce0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 NULL values res
12cf0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 ult.** in NULL p
12d00 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 ointers. All ot
12d10 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 her values are i
12d20 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 n their UTF-8 ze
12d30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
12d40 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e string represen
12d50 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e tation as return
12d60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
12d70 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a olumn_text()]..*
12d80 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
12d90 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 ble might consis
12da0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 t of one or more
12db0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
12dc0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ons..** It is no
12dd0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 t safe to pass a
12de0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 result table di
12df0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 rectly to [sqlit
12e00 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 e3_free()]..** A
12e10 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 result table sh
12e20 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 ould be dealloca
12e30 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
12e40 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
12e50 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 ..**.** As an ex
12e60 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 ample of the res
12e70 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 ult table format
12e80 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 , suppose a quer
12e90 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 y result.** is a
12ea0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
12eb0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
12ec0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d e>.** Nam
12ed0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a e | Age.*
12ee0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d * -------
12ef0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
12f00 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 .** Alice
12f10 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 | 43.**
12f20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 Bob
12f30 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 | 28.**
12f40 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 Cindy | 2
12f50 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 1.** </pre></blo
12f60 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
12f70 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c here are two col
12f80 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 umn (M==2) and t
12f90 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 hree rows (N==3)
12fa0 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 . Thus the.** r
12fb0 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 esult table has
12fc0 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 8 entries. Supp
12fd0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 ose the result t
12fe0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a able is stored.*
12ff0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 * in an array na
13000 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 mes azResult. T
13010 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c hen azResult hol
13020 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a ds this content:
13030 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
13040 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
13050 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
13060 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 0] = "Name";.**
13070 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
13080 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a #91;1] = "Age";.
13090 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
130a0 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 lt[2] = "Ali
130b0 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 ce";.** a
130c0 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d zResult[3] =
130d0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "43";.**
130e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d azResult[4]
130f0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 = "Bob";.**
13100 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
13110 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 ;5] = "28";.**
13120 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
13130 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 91;6] = "Cindy";
13140 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
13150 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 ult[7] = "21
13160 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
13170 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
13180 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
13190 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
131a0 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
131b0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
131c0 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
131d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
131e0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
131f0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
13200 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
13210 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
13220 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 turns a result t
13230 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 able to the.** p
13240 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 ointer given in
13250 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 its 3rd paramete
13260 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 r..**.** After t
13270 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 he application h
13280 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
13290 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
132a0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
132b0 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 73 68 6f 75 le(),.** it shou
132c0 6c 64 20 70 61 73 73 20 74 68 65 20 72 65 73 75 ld pass the resu
132d0 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 lt table pointer
132e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
132f0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 _table() in orde
13300 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 r to.** release
13310 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 the memory that
13320 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 was malloced. B
13330 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 ecause of the wa
13340 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 y the.** [sqlite
13350 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 3_malloc()] happ
13360 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 ens within sqlit
13370 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 e3_get_table(),
13380 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 the calling.** f
13390 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 unction must not
133a0 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 try to call [sq
133b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 lite3_free()] di
133c0 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a rectly. Only.**
133d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 [sqlite3_free_t
133e0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 able()] is able
133f0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d to release the m
13400 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 emory properly a
13410 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a nd safely..**.**
13420 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ^(The sqlite3_g
13430 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 et_table() inter
13440 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
13450 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 ted as a wrapper
13460 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 around.** [sqli
13470 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 te3_exec()]. Th
13480 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
13490 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f ble() routine do
134a0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 es not have acce
134b0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 ss.** to any int
134c0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 ernal data struc
134d0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e tures of SQLite.
134e0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 It uses only t
134f0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 he public.** int
13500 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 erface defined h
13510 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 ere. As a conse
13520 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 quence, errors t
13530 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 hat occur in the
13540 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 .** wrapper laye
13550 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 r outside of the
13560 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 internal [sqlit
13570 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 e3_exec()] call
13580 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 are not.** refle
13590 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 cted in subseque
135a0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
135b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
135c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 or.** [sqlite3_e
135d0 72 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a 2f 0a 69 rrmsg()].)^.*/.i
135e0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 nt sqlite3_get_t
135f0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 able(. sqlite3
13600 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a *db, /*
13610 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
13620 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
13630 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 r *zSql, /*
13640 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 SQL to be evalua
13650 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ted */. char **
13660 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f *pazResult, /
13670 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 * Results of the
13680 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 query */. int
13690 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 *pnRow,
136a0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
136b0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 esult rows writt
136c0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 en here */. int
136d0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 *pnColumn,
136e0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
136f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 result columns w
13700 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
13710 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 char **pzErrmsg
13720 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 /* Error
13730 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 msg written here
13740 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 */.);.void sqli
13750 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 te3_free_table(c
13760 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a har **result);..
13770 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
13780 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 Formatted String
13790 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 Printing Functi
137a0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
137b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 routines are wor
137c0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 k-alikes of the
137d0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c "printf()" famil
137e0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a y of functions.*
137f0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 * from the stand
13800 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
13810 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
13820 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
13830 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
13840 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
13850 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
13860 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
13870 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
13880 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
13890 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
138a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
138b0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
138c0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
138d0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
138e0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 _free()]. ^Both
138f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
13900 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
13910 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d er if [sqlite3_m
13920 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 alloc()] is unab
13930 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 le to allocate e
13940 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 nough.** memory
13950 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 to hold the resu
13960 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a lting string..**
13970 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 .** ^(In sqlite3
13980 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _snprintf() rout
13990 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
139a0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 o "snprintf()" f
139b0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 rom.** the stand
139c0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 ard C library.
139d0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 The result is wr
139e0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a itten into the.*
139f0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 * buffer supplie
13a00 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
13a10 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 parameter whose
13a20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 size is given by
13a30 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 .** the first pa
13a40 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 rameter. Note th
13a50 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 at the order of
13a60 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f the.** first two
13a70 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 parameters is r
13a80 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 eversed from snp
13a90 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 rintf().)^ This
13aa0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 is an.** histor
13ab0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 ical accident th
13ac0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 at cannot be fix
13ad0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ed without break
13ae0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ing.** backwards
13af0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 compatibility.
13b00 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 ^(Note also tha
13b10 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e t sqlite3_snprin
13b20 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 tf().** returns
13b30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 a pointer to its
13b40 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 buffer instead
13b50 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
13b60 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 .** characters a
13b70 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 ctually written
13b80 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e into the buffer.
13b90 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 )^ We admit tha
13ba0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 t.** the number
13bb0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 of characters wr
13bc0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 itten would be a
13bd0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 more useful ret
13be0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 urn.** value but
13bf0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 we cannot chang
13c00 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 e the implementa
13c10 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
13c20 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f snprintf().** no
13c30 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 w without breaki
13c40 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ng compatibility
13c50 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 ..**.** ^As long
13c60 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 as the buffer s
13c70 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 ize is greater t
13c80 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 han zero, sqlite
13c90 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
13ca0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
13cb0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c the buffer is al
13cc0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e ways zero-termin
13cd0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 ated. ^The firs
13ce0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 t.** parameter "
13cf0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 n" is the total
13d00 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
13d10 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 er, including sp
13d20 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a ace for.** the z
13d30 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
13d40 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 So the longest
13d50 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 string that can
13d60 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a be completely.**
13d70 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 written will be
13d80 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e n-1 characters.
13d90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
13da0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d tines all implem
13db0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f ent some additio
13dc0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a nal formatting.*
13dd0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 * options that a
13de0 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f re useful for co
13df0 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 nstructing SQL s
13e00 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c tatements..** Al
13e10 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 l of the usual p
13e20 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 rintf() formatti
13e30 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 ng options apply
13e40 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 . In addition,
13e50 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 there.** is are
13e60 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 "%q", "%Q", and
13e70 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a "%z" options..**
13e80 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 .** ^(The %q opt
13e90 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 ion works like %
13ea0 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 s in that it sub
13eb0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d stitutes a null-
13ec0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
13ed0 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 ring from the ar
13ee0 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 gument list. Bu
13ef0 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 t %q also double
13f00 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 s every '\'' cha
13f10 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 racter..** %q is
13f20 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 designed for us
13f30 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e e inside a strin
13f40 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 g literal.)^ By
13f50 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 doubling each '
13f60 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 \''.** character
13f70 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 it escapes that
13f80 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 character and a
13f90 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 llows it to be i
13fa0 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 nserted into.**
13fb0 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a the string..**.*
13fc0 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 * For example, a
13fd0 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 ssume the string
13fe0 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 variable zText
13ff0 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 contains text as
14000 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
14010 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
14020 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 >.** char *zTex
14030 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 t = "It's a happ
14040 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 y day!";.** </pr
14050 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
14060 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 **.** One can us
14070 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 e this text in a
14080 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
14090 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
140a0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
140b0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 re>.** char *zS
140c0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 QL = sqlite3_mpr
140d0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 intf("INSERT INT
140e0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 O table VALUES('
140f0 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a %q')", zText);.*
14100 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
14110 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
14120 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
14130 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
14140 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
14150 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 e>.**.** Because
14160 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 the %q format s
14170 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 tring is used, t
14180 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 he '\'' characte
14190 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 r in zText.** is
141a0 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 escaped and the
141b0 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 SQL generated i
141c0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
141d0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
141e0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 <pre>.** INSERT
141f0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c INTO table1 VAL
14200 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 UES('It''s a hap
14210 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 py day!').** </p
14220 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
14230 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 .**.** This is c
14240 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 orrect. Had we
14250 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 used %s instead
14260 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 of %q, the gener
14270 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c ated SQL.** woul
14280 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 d have looked li
14290 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c ke this:.**.** <
142a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
142b0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f .** INSERT INTO
142c0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
142d0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 It's a happy day
142e0 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f !');.** </pre></
142f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
14300 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 * This second ex
14310 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 ample is an SQL
14320 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 syntax error. A
14330 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 s a general rule
14340 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 you should.** a
14350 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 lways use %q ins
14360 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 tead of %s when
14370 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 inserting text i
14380 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 nto a string lit
14390 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 eral..**.** ^(Th
143a0 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b e %Q option work
143b0 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 s like %q except
143c0 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 it also adds si
143d0 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 ngle quotes arou
143e0 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 nd.** the outsid
143f0 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 e of the total s
14400 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e tring. Addition
14410 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 ally, if the par
14420 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a ameter in the.**
14430 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 argument list i
14440 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
14450 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 , %Q substitutes
14460 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 the text "NULL"
14470 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e (without.** sin
14480 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 gle quotes).)^
14490 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c So, for example,
144a0 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a one could say:.
144b0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
144c0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
144d0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 *zSQL = sqlite3
144e0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 _mprintf("INSERT
144f0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 INTO table VALU
14500 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b ES(%Q)", zText);
14510 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
14520 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
14530 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
14540 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
14550 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
14560 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ote>.**.** The c
14570 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 ode above will r
14580 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 ender a correct
14590 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
145a0 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 the zSQL.** var
145b0 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 iable even if th
145c0 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 e zText variable
145d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
145e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 er..**.** ^(The
145f0 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 "%z" formatting
14600 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
14610 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 e "%s" but with
14620 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 the.** addition
14630 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 that after the s
14640 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 tring has been r
14650 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 ead and copied i
14660 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c nto.** the resul
14670 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 t, [sqlite3_free
14680 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e ()] is called on
14690 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
146a0 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 g.)^.*/.char *sq
146b0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f lite3_mprintf(co
146c0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a nst char*,...);.
146d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d char *sqlite3_vm
146e0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 printf(const cha
146f0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 r*, va_list);.ch
14700 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 ar *sqlite3_snpr
14710 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 intf(int,char*,c
14720 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 onst char*, ...)
14730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
14740 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
14750 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a tion Subsystem.*
14760 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 *.** The SQLite
14770 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 core uses these
14780 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 three routines f
14790 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 or all of its ow
147a0 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 n.** internal me
147b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
147c0 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e needs. "Core" in
147d0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 the previous se
147e0 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e ntence.** does n
147f0 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 ot include opera
14800 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
14810 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 ific VFS impleme
14820 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a ntation. The.**
14830 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 Windows VFS use
14840 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 s native malloc(
14850 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 ) and free() for
14860 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 some operations
14870 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
14880 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f ite3_malloc() ro
14890 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
148a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f pointer to a blo
148b0 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 ck.** of memory
148c0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
148d0 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 in length, wher
148e0 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d e N is the param
148f0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c eter..** ^If sql
14900 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 ite3_malloc() is
14910 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 unable to obtai
14920 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 n sufficient fre
14930 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 e.** memory, it
14940 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
14950 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 ointer. ^If the
14960 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a parameter N to.
14970 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
14980 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e c() is zero or n
14990 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c egative then sql
149a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 ite3_malloc() re
149b0 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 turns.** a NULL
149c0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
149d0 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f Calling sqlite3_
149e0 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f free() with a po
149f0 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 inter previously
14a00 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 returned.** by
14a10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14a20 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c or sqlite3_real
14a30 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 loc() releases t
14a40 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a hat memory so.**
14a50 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 that it might b
14a60 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 e reused. ^The
14a70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 sqlite3_free() r
14a80 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e outine is.** a n
14a90 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 o-op if is calle
14aa0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f d with a NULL po
14ab0 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 inter. Passing
14ac0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
14ad0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 * to sqlite3_fre
14ae0 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e e() is harmless.
14af0 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 After being fr
14b00 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 eed, memory.** s
14b10 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 hould neither be
14b20 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 read nor writte
14b30 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 n. Even reading
14b40 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 previously free
14b50 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 d.** memory migh
14b60 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 t result in a se
14b70 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 gmentation fault
14b80 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 or other severe
14b90 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 error..** Memor
14ba0 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 y corruption, a
14bb0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 segmentation fau
14bc0 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 lt, or other sev
14bd0 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 ere error.** mig
14be0 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c ht result if sql
14bf0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 ite3_free() is c
14c00 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e alled with a non
14c10 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 -NULL pointer th
14c20 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 at.** was not ob
14c30 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 tained from sqli
14c40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 te3_malloc() or
14c50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
14c60 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 )..**.** ^(The s
14c70 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
14c80 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
14c90 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a pts to resize a.
14ca0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 ** prior memory
14cb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 allocation to be
14cc0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
14cd0 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 s, where N is th
14ce0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 e.** second para
14cf0 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f meter. The 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 72 65 73 69 7a 65 64 20 69 73 20 74 be resized is t
14d20 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 he first.** para
14d30 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 meter.)^ ^ If th
14d40 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
14d50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 r to sqlite3_rea
14d60 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e lloc().** is a N
14d70 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
14d80 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 its behavior is
14d90 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 identical to ca
14da0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 lling.** sqlite3
14db0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 _malloc(N) where
14dc0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
14dd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
14de0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
14df0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f .** ^If the seco
14e00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
14e10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
14e20 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 ) is zero or.**
14e30 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 negative then th
14e40 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 e behavior is ex
14e50 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 actly the same a
14e60 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c s calling.** sql
14e70 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 ite3_free(P) whe
14e80 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 re P is the firs
14e90 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
14ea0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
14eb0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 ..** ^sqlite3_re
14ec0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 alloc() returns
14ed0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d a pointer to a m
14ee0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14ef0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 .** of at least
14f00 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 N bytes in size
14f10 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 or NULL if suffi
14f20 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 cient memory is
14f30 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 unavailable..**
14f40 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a ^If M is the siz
14f50 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 e of the prior a
14f60 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 llocation, then
14f70 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a min(N,M) bytes.*
14f80 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 * of the prior a
14f90 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f llocation are co
14fa0 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 pied into the be
14fb0 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 ginning of buffe
14fc0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 r returned.** by
14fd0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
14fe0 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 () and the prior
14ff0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 allocation is f
15000 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c reed..** ^If sql
15010 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 ite3_realloc() r
15020 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 eturns NULL, the
15030 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f n the prior allo
15040 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 cation.** is not
15050 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 freed..**.** ^T
15060 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e he memory return
15070 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 ed by sqlite3_ma
15080 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 lloc() and sqlit
15090 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 e3_realloc().**
150a0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 is always aligne
150b0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e d to at least an
150c0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8 byte boundary
150d0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 ..**.** In SQLit
150e0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 e version 3.5.0
150f0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 and 3.5.1, it wa
15100 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 s possible to de
15110 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 fine.** the SQLI
15120 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 TE_OMIT_MEMORY_A
15130 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 LLOCATION which
15140 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 would cause the
15150 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c built-in.** impl
15160 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
15170 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ese routines to
15180 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 be omitted. Tha
15190 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 t capability.**
151a0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f is no longer pro
151b0 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 vided. Only bui
151c0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
151d0 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 ocators can be u
151e0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 sed..**.** The W
151f0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 indows OS interf
15200 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a ace layer calls.
15210 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 ** the system ma
15220 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 lloc() and free(
15230 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 ) directly when
15240 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 converting.** fi
15250 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 lenames between
15260 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 the UTF-8 encodi
15270 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 ng used by SQLit
15280 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 e.** and whateve
15290 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 r filename encod
152a0 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 ing is used by t
152b0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 he particular Wi
152c0 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c ndows.** install
152d0 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 ation. Memory a
152e0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 llocation errors
152f0 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 are detected, b
15300 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 ut.** they are r
15310 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 eported back as
15320 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
15330 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
15340 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 IOERR] rather th
15350 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d an [SQLITE_NOMEM
15360 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 ]..**.** The poi
15370 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 nter arguments t
15380 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
15390 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
153a0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 realloc()].** mu
153b0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c st be either NUL
153c0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 L or else pointe
153d0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d rs obtained from
153e0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f a prior.** invo
153f0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
15400 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
15410 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
15420 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a ()] that have.**
15430 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 not yet been re
15440 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 leased..**.** Th
15450 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
15460 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 st not read or w
15470 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 rite any part of
15480 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d .** a block of m
15490 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 emory after it h
154a0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 as been released
154b0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
154c0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 e3_free()] or [s
154d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
154e0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 ]..*/.void *sqli
154f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b te3_malloc(int);
15500 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 .void *sqlite3_r
15510 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e ealloc(void*, in
15520 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
15530 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f _free(void*);../
15540 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
15550 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 emory Allocator
15560 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a Statistics.**.**
15570 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 SQLite provides
15580 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 these two inter
15590 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 faces for report
155a0 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 ing on the statu
155b0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c s.** of the [sql
155c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 ite3_malloc()],
155d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
155e0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 , and [sqlite3_r
155f0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 ealloc()].** rou
15600 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 tines, which for
15610 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d m the built-in m
15620 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
15630 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a subsystem..**.*
15640 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
15650 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 memory_used()] r
15660 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
15670 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
15680 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 es.** of memory
15690 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 currently outsta
156a0 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 nding (malloced
156b0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a but not freed)..
156c0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
156d0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
156e0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 r()] routine ret
156f0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d urns the maximum
15700 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 .** value of [sq
15710 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
15720 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 d()] since the h
15730 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
15740 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 * was last reset
15750 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 . ^The values r
15760 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
15770 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
15780 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
15790 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
157a0 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 ter()] include a
157b0 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 ny overhead.** a
157c0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 dded by SQLite i
157d0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 n its implementa
157e0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
157f0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 _malloc()],.** b
15800 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 ut not overhead
15810 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 added by the any
15820 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 underlying syst
15830 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f em library.** ro
15840 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c utines that [sql
15850 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d ite3_malloc()] m
15860 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e ay call..**.** ^
15870 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d The memory high-
15880 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 water mark is re
15890 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 set to the curre
158a0 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b nt value of.** [
158b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
158c0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e sed()] if and on
158d0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 ly if the parame
158e0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
158f0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
15900 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 ter()] is true.
15910 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 ^The value retu
15920 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 rned.** by [sqli
15930 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
15940 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 ater(1)] is the
15950 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a high-water mark.
15960 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 ** prior to the
15970 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 reset..*/.sqlite
15980 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
15990 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 memory_used(void
159a0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 );.sqlite3_int64
159b0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
159c0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 highwater(int re
159d0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a setFlag);../*.**
159e0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 CAPI3REF: Pseud
159f0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 o-Random Number
15a00 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 Generator.**.**
15a10 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 SQLite contains
15a20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 a high-quality p
15a30 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d seudo-random num
15a40 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 ber generator (P
15a50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 RNG) used to.**
15a60 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 select random [R
15a70 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 OWID | ROWIDs] w
15a80 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 hen inserting ne
15a90 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 w records into a
15aa0 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 table that.** a
15ab0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 lready uses the
15ac0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 largest possible
15ad0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 [ROWID]. The P
15ae0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 RNG is also used
15af0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c for.** the buil
15b00 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e d-in random() an
15b10 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 d randomblob() S
15b20 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 QL functions. T
15b30 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
15b40 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 lows.** applicat
15b50 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 ions to access t
15b60 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 he same PRNG for
15b70 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e other purposes.
15b80 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 .**.** ^A call t
15b90 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 o this routine s
15ba0 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 tores N bytes of
15bb0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
15bc0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a buffer P..**.**
15bd0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 ^The first time
15be0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
15bf0 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 invoked (either
15c00 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 internally or b
15c10 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 y.** the applica
15c20 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 tion) the PRNG i
15c30 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 s seeded using r
15c40 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e andomness obtain
15c50 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 ed.** from the x
15c60 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f Randomness metho
15c70 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 d of the default
15c80 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
15c90 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c bject..** ^On al
15ca0 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 l subsequent inv
15cb0 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 ocations, the ps
15cc0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 eudo-randomness
15cd0 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 is generated.**
15ce0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 internally and w
15cf0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 ithout recourse
15d00 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
15d10 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 vfs] xRandomness
15d20 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 .** method..*/.v
15d30 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 oid sqlite3_rand
15d40 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f omness(int N, vo
15d50 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id *P);../*.** C
15d60 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 API3REF: Compile
15d70 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 -Time Authorizat
15d80 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ion Callbacks.**
15d90 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
15da0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 e registers a au
15db0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
15dc0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 k with a particu
15dd0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 lar.** [database
15de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 connection], su
15df0 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 pplied in the fi
15e00 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
15e10 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 ^The authorizer
15e20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
15e30 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 oked as SQL stat
15e40 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 ements are being
15e50 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 compiled.** by
15e60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
15e70 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
15e80 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 nts [sqlite3_pre
15e90 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b pare_v2()],.** [
15ea0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
15eb0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 6()] and [sqlite
15ec0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
15ed0 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a ]. ^At various.
15ee0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 ** points during
15ef0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e the compilation
15f00 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 process, as log
15f10 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 ic is being crea
15f20 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 ted.** to perfor
15f30 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e m various action
15f40 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 s, the authorize
15f50 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
15f60 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 voked to.** see
15f70 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 if those actions
15f80 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e are allowed. ^
15f90 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
15fa0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a allback should.*
15fb0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
15fc0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 _OK] to allow th
15fd0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 e action, [SQLIT
15fe0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 E_IGNORE] to dis
15ff0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 allow the.** spe
16000 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 cific action but
16010 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 allow the SQL s
16020 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 tatement to cont
16030 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f inue to be.** co
16040 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 mpiled, or [SQLI
16050 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 TE_DENY] to caus
16060 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c e the entire SQL
16070 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
16080 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 .** rejected wit
16090 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 h an error. ^If
160a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
160b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
160c0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 .** any value ot
160d0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
160e0 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 _IGNORE], [SQLIT
160f0 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 E_OK], or [SQLIT
16100 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 E_DENY].** then
16110 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
16120 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
16130 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
16140 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 at triggered.**
16150 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 the authorizer w
16160 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
16170 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
16180 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 **.** When the c
16190 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
161a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 [SQLITE_OK], tha
161b0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 t means the oper
161c0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 ation.** request
161d0 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e ed is ok. ^When
161e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
161f0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 turns [SQLITE_DE
16200 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c NY], the.** [sql
16210 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
16220 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
16230 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
16240 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 ered the.** auth
16250 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
16260 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
16270 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e essage explainin
16280 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 g that.** access
16290 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a is denied. .**.
162a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 ** ^The first pa
162b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
162c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
162d0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ck is a copy of
162e0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 the third.** par
162f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
16300 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
16310 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 izer() interface
16320 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
16330 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
16340 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
16350 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 integer [SQLITE
16360 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 _COPY | action c
16370 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 ode] that specif
16380 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 ies.** the parti
16390 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 cular action to
163a0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e be authorized. ^
163b0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 The third throug
163c0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 h sixth paramete
163d0 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c rs.** to the cal
163e0 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 lback are zero-t
163f0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
16400 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 s that contain a
16410 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 dditional.** det
16420 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
16430 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
16440 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 orized..**.** ^I
16450 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 f the action cod
16460 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 e is [SQLITE_REA
16470 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 D].** and the ca
16480 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
16490 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
164a0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 hen the.** [prep
164b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
164c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e statement is con
164d0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 structed to subs
164e0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c titute.** a NULL
164f0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 value in place
16500 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
16510 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 umn that would h
16520 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 ave.** been read
16530 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 if [SQLITE_OK]
16540 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 had been returne
16550 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f d. The [SQLITE_
16560 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 IGNORE].** retur
16570 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
16580 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 deny an untrust
16590 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 ed user access t
165a0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 o individual.**
165b0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 columns of a tab
165c0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 le..** ^If the a
165d0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
165e0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e QLITE_DELETE] an
165f0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
16600 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
16610 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
16620 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 he [DELETE] oper
16630 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 ation proceeds b
16640 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 ut the.** [trunc
16650 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
16660 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e ] is disabled an
16670 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 d all rows are d
16680 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 eleted individua
16690 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 lly..**.** An au
166a0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 thorizer is used
166b0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 when [sqlite3_p
166c0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 repare | prepari
166d0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ng].** SQL state
166e0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e ments from an un
166f0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 trusted source,
16700 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 to ensure that t
16710 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
16720 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 s.** do not try
16730 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 to access data t
16740 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f hey are not allo
16750 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 wed to see, or t
16760 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
16770 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 ** try to execut
16780 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 e malicious stat
16790 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 ements that dama
167a0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ge the database.
167b0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 For.** example
167c0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
167d0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 may allow a use
167e0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 r to enter arbit
167f0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 rary.** SQL quer
16800 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 ies for evaluati
16810 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 on by a database
16820 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 . But the appli
16830 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e cation does.** n
16840 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 ot want the user
16850 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d to be able to m
16860 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 ake arbitrary ch
16870 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 anges to the.**
16880 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 database. An au
16890 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 thorizer could t
168a0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c hen be put in pl
168b0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a ace while the.**
168c0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
168d0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 L is being [sqli
168e0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
168f0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 epared] that.**
16900 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 disallows everyt
16910 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c hing except [SEL
16920 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e ECT] statements.
16930 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
16940 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f ons that need to
16950 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f process SQL fro
16960 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 m untrusted sour
16970 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 ces.** might als
16980 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 o consider lower
16990 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d ing resource lim
169a0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 its using [sqlit
169b0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 e3_limit()].** a
169c0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 nd limiting data
169d0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 base size using
169e0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f the [max_page_co
169f0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a unt] [PRAGMA].**
16a00 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 in addition to
16a10 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 using an authori
16a20 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c zer..**.** ^(Onl
16a30 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
16a40 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
16a50 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
16a60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
16a70 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
16a80 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
16a90 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
16aa0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
16ab0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
16ac0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 .)^ ^Disable th
16ad0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 e authorizer by
16ae0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c installing a NUL
16af0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 L callback..** T
16b00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 he authorizer is
16b10 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
16b20 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ault..**.** The
16b30 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
16b40 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ack must not do
16b50 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
16b60 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
16b70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
16b80 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
16b90 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 d the authorizer
16ba0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f callback..** No
16bb0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 te that [sqlite3
16bc0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
16bd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
16be0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 ()] both modify
16bf0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 their.** databas
16c00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f e connections fo
16c10 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 r the meaning of
16c20 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 "modify" in thi
16c30 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a s paragraph..**.
16c40 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 ** ^When [sqlite
16c50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
16c60 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 is used to prepa
16c70 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 re a statement,
16c80 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
16c90 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 might be re-pre
16ca0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 pared during [sq
16cb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 lite3_step()] du
16cc0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d e to a .** schem
16cd0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 a change. Hence
16ce0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
16cf0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 n should ensure
16d00 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 that the.** corr
16d10 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 ect authorizer c
16d20 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 allback remains
16d30 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 in place during
16d40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
16d50 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 p()]..**.** ^Not
16d60 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f e that the autho
16d70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
16d80 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 s invoked only d
16d90 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 uring.** [sqlite
16da0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
16db0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 its variants. A
16dc0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 uthorization is
16dd0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 not.** performed
16de0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e during statemen
16df0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 t evaluation in
16e00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
16e10 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 , unless.** as s
16e20 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 tated in the pre
16e30 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c vious paragraph,
16e40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
16e50 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 invokes.** sqlit
16e60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 e3_prepare_v2()
16e70 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 to reprepare a s
16e80 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 tatement after a
16e90 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a schema change..
16ea0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
16eb0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 et_authorizer(.
16ec0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 sqlite3*,. int
16ed0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c (*xAuth)(void*,
16ee0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
16ef0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
16f00 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
16f10 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 ar*),. void *pU
16f20 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a serData.);../*.*
16f30 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
16f40 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f orizer Return Co
16f50 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
16f60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
16f70 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
16f80 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
16f90 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 tion] must.** re
16fa0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c turn either [SQL
16fb0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f ITE_OK] or one o
16fc0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 f these two cons
16fd0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a tants in order.*
16fe0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 * to signal SQLi
16ff0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f te whether or no
17000 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 t the action is
17010 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 permitted. See
17020 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
17030 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
17040 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 authorizer docu
17050 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 mentation] for a
17060 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
17070 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 ormation..*/.#de
17080 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 fine SQLITE_DENY
17090 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 1 /* Abort
170a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
170b0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 t with an error
170c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
170d0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 E_IGNORE 2 /*
170e0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 Don't allow acce
170f0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 ss, but don't ge
17100 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 nerate an error
17110 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
17120 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 EF: Authorizer A
17130 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a ction Codes.**.*
17140 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 * The [sqlite3_s
17150 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d et_authorizer()]
17160 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
17170 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 ters a callback
17180 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 function.** that
17190 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 is invoked to a
171a0 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e uthorize certain
171b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
171c0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 ctions. The.**
171d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
171e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
171f0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 is an integer c
17200 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 ode that specifi
17210 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f es.** what actio
17220 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f n is being autho
17230 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 rized. These ar
17240 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 e the integer ac
17250 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a tion codes that.
17260 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
17270 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 r callback may b
17280 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 e passed..**.**
17290 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 These action cod
172a0 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 e values signify
172b0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 what kind of op
172c0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 eration is to be
172d0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 .** authorized.
172e0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 The 3rd and 4th
172f0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
17300 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e he authorization
17310 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e .** callback fun
17320 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 ction will be pa
17330 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c rameters or NULL
17340 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 depending on wh
17350 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ich of these.**
17360 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 codes is used as
17370 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
17380 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 35 74 68 meter. ^The 5th
17390 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
173a0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
173b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
173c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
173d0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 base ("main", "t
173e0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 emp",.** etc.) i
173f0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 5e f applicable. ^
17400 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 The 6th paramete
17410 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 r to the authori
17420 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 zer callback.**
17430 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
17440 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 he inner-most tr
17450 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 igger or view th
17460 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c at is responsibl
17470 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 e for.** the acc
17480 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e ess attempt or N
17490 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 ULL if this acce
174a0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 ss attempt is di
174b0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 rectly from.** t
174c0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 op-level SQL cod
174d0 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a e..*/./*********
174e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
174f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
17500 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a ** 3rd *********
17510 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a *** 4th ********
17520 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ***/.#define SQL
17530 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 ITE_CREATE_INDEX
17540 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 1 /*
17550 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
17560 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
17570 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17580 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 TE_CREATE_TABLE
17590 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 2 /*
175a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
175b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
175c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
175d0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e E_CREATE_TEMP_IN
175e0 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 DEX 3 /* I
175f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
17600 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
17610 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17620 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 _CREATE_TEMP_TAB
17630 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 LE 4 /* Ta
17640 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
17650 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
17660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17670 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 CREATE_TEMP_TRIG
17680 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 GER 5 /* Tri
17690 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
176a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
176b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
176c0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 REATE_TEMP_VIEW
176d0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 6 /* View
176e0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
176f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
17700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
17710 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 EATE_TRIGGER
17720 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 7 /* Trigg
17730 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
17740 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
17750 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
17760 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 ATE_VIEW
17770 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 8 /* View N
17780 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
17790 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
177a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 fine SQLITE_DELE
177b0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
177c0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 9 /* Table N
177d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
177e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
177f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
17800 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
17810 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 10 /* Index Na
17820 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
17830 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
17840 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
17850 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 ABLE 1
17860 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 1 /* Table Nam
17870 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
17880 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
17890 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
178a0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 MP_INDEX 12
178b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
178c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
178d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
178e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
178f0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 P_TABLE 13
17900 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
17910 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
17920 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
17930 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
17940 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 _TRIGGER 14
17950 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
17960 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
17970 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
17980 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
17990 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 VIEW 15
179a0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
179b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
179c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
179d0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 LITE_DROP_TRIGGE
179e0 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f R 16 /
179f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
17a00 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
17a10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
17a20 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 ITE_DROP_VIEW
17a30 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 17 /*
17a40 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
17a50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
17a60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17a70 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 TE_INSERT
17a80 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 18 /*
17a90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
17aa0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
17ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17ac0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 E_PRAGMA
17ad0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 19 /* P
17ae0 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 ragma Name 1
17af0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a st arg or NULL *
17b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17b10 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
17b20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 20 /* Ta
17b30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
17b40 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
17b50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17b60 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 SELECT
17b70 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 21 /* NUL
17b80 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c L NUL
17b90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
17ba0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
17bb0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 RANSACTION
17bc0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 22 /* Oper
17bd0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c ation NULL
17be0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
17bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 define SQLITE_UP
17c00 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 DATE
17c10 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 23 /* Table
17c20 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d Name Colum
17c30 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 n Name */.#d
17c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 efine SQLITE_ATT
17c50 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
17c60 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 24 /* Filena
17c70 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 me NULL
17c80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
17c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 fine SQLITE_DETA
17ca0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
17cb0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 25 /* Databas
17cc0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 e Name NULL
17cd0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
17ce0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 ine SQLITE_ALTER
17cf0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
17d00 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 26 /* Database
17d10 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
17d20 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
17d30 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 ne SQLITE_REINDE
17d40 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 X 2
17d50 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 7 /* Index Nam
17d60 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
17d70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
17d80 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 e SQLITE_ANALYZE
17d90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 28
17da0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
17db0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
17dc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
17dd0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 SQLITE_CREATE_V
17de0 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 TABLE 29
17df0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
17e00 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 Module Name
17e10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
17e20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 SQLITE_DROP_VTAB
17e30 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 LE 30
17e40 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
17e50 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 Module Name
17e60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
17e70 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 QLITE_FUNCTION
17e80 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 31
17e90 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 /* NULL
17ea0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 Function Name
17eb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17ec0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 LITE_SAVEPOINT
17ed0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 32 /
17ee0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 * Operation
17ef0 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 Savepoint Name
17f00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
17f10 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 ITE_COPY
17f20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 0 /*
17f30 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 No longer used
17f40 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
17f50 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 EF: Tracing And
17f60 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 Profiling Functi
17f70 6f 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e ons.** EXPERIMEN
17f80 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TAL.**.** These
17f90 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 routines registe
17fa0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 r callback funct
17fb0 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 ions that can be
17fc0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 used for.** tra
17fd0 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 cing and profili
17fe0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e ng the execution
17ff0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e of SQL statemen
18000 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 ts..**.** ^The c
18010 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
18020 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
18030 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 qlite3_trace() i
18040 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 s invoked at.**
18050 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 various times wh
18060 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d en an SQL statem
18070 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e ent is being run
18080 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 by [sqlite3_ste
18090 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 p()]..** ^The sq
180a0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 lite3_trace() ca
180b0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
180c0 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 d with a UTF-8 r
180d0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a endering of the.
180e0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
180f0 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 text as the sta
18100 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 tement first beg
18110 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a ins executing..*
18120 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 * ^(Additional s
18130 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
18140 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f allbacks might o
18150 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 ccur.** as each
18160 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f triggered subpro
18170 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e gram is entered.
18180 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 The callbacks
18190 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 for triggers.**
181a0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 contain a UTF-8
181b0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 SQL comment that
181c0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 identifies the
181d0 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a trigger.)^.**.**
181e0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
181f0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
18200 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 ed by sqlite3_pr
18210 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b ofile() is invok
18220 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 ed.** as each SQ
18230 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 L statement fini
18240 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 shes. ^The prof
18250 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e ile callback con
18260 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 tains.** the ori
18270 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 ginal statement
18280 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 text and an esti
18290 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f mate of wall-clo
182a0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f ck time.** of ho
182b0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 w long that stat
182c0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 ement took to ru
182d0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 n..*/.SQLITE_EXP
182e0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a ERIMENTAL void *
182f0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 sqlite3_trace(sq
18300 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 lite3*, void(*xT
18310 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 race)(void*,cons
18320 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 t char*), void*)
18330 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d ;.SQLITE_EXPERIM
18340 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 ENTAL void *sqli
18350 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 te3_profile(sqli
18360 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 te3*,. void(*x
18370 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 Profile)(void*,c
18380 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 onst char*,sqlit
18390 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 e3_uint64), void
183a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
183b0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 REF: Query Progr
183c0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ess Callbacks.**
183d0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
183e0 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 e configures a c
183f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
18400 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 - the.** progre
18410 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 ss callback - th
18420 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 at is invoked pe
18430 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e riodically durin
18440 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e g long.** runnin
18450 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 g calls to [sqli
18460 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 te3_exec()], [sq
18470 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e lite3_step()] an
18480 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 d.** [sqlite3_ge
18490 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 t_table()]. An
184a0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 example use for
184b0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 this.** interfac
184c0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 e is to keep a G
184d0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e UI updated durin
184e0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e g a large query.
184f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 .**.** ^If the p
18500 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
18510 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
18520 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e o, the operation
18530 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 is.** interrupt
18540 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 ed. This featur
18550 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
18560 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 implement a.**
18570 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 "Cancel" button
18580 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 on a GUI progres
18590 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a s dialog box..**
185a0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 .** The progress
185b0 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f handler must no
185c0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
185d0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
185e0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
185f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
18600 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 nvoked the progr
18610 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 ess handler..**
18620 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
18630 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
18640 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
18650 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
18660 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
18670 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
18680 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
18690 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
186a0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
186b0 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 *.*/.void sqlite
186c0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
186d0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
186e0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c , int(*)(void*),
186f0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
18700 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e CAPI3REF: Openin
18710 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 g A New Database
18720 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a Connection.**.*
18730 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
18740 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 s open an SQLite
18750 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
18760 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 hose name is giv
18770 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c en by the.** fil
18780 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 ename argument.
18790 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 ^The filename ar
187a0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 gument is interp
187b0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 reted as UTF-8 f
187c0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 or.** sqlite3_op
187d0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
187e0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 _open_v2() and a
187f0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 s UTF-16 in the
18800 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f native byte.** o
18810 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 rder for sqlite3
18820 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b _open16(). ^(A [
18830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18840 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 ion] handle is u
18850 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e sually.** return
18860 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 ed in *ppDb, eve
18870 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 n if an error oc
18880 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 curs. The only
18890 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 exception is tha
188a0 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 t.** if SQLite i
188b0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
188c0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 cate memory to h
188d0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 old the [sqlite3
188e0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e ] object,.** a N
188f0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 ULL will be writ
18900 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 ten into *ppDb i
18910 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e nstead of a poin
18920 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
18930 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 te3].** object.)
18940 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 ^ ^(If the datab
18950 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 ase is opened (a
18960 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 nd/or created) s
18970 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 uccessfully, the
18980 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d n.** [SQLITE_OK]
18990 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f is returned. O
189a0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
189b0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
189c0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 rned.)^ ^The.**
189d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
189e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 )] or [sqlite3_e
189f0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 rrmsg16()] routi
18a00 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nes can be used
18a10 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 to obtain.** an
18a20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 English language
18a30 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 description of
18a40 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 the error follow
18a50 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 ing a failure of
18a60 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 any.** of the s
18a70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f qlite3_open() ro
18a80 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 utines..**.** ^T
18a90 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 he default encod
18aa0 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 ing for the data
18ab0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 base will be UTF
18ac0 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 -8 if.** sqlite3
18ad0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
18ae0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
18af0 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 called and.** UT
18b00 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
18b10 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 ve byte order if
18b20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
18b30 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a ) is used..**.**
18b40 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 Whether or not
18b50 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
18b60 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 when it is opene
18b70 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 d, resources.**
18b80 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
18b90 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
18ba0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
18bb0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 should be relea
18bc0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e sed by.** passin
18bd0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 g it to [sqlite3
18be0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 _close()] when i
18bf0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 t is no longer r
18c00 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 equired..**.** T
18c10 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f he sqlite3_open_
18c20 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 v2() interface w
18c30 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 orks like sqlite
18c40 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 3_open().** exce
18c50 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 pt that it accep
18c60 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 ts two additiona
18c70 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 l parameters for
18c80 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 additional cont
18c90 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 rol.** over the
18ca0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
18cb0 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 nection. ^(The
18cc0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
18cd0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 to.** sqlite3_op
18ce0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 en_v2() can take
18cf0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 one of.** the f
18d00 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 ollowing three v
18d10 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c alues, optionall
18d20 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 y combined with
18d30 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
18d40 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b OPEN_NOMUTEX], [
18d50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
18d60 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f MUTEX], [SQLITE_
18d70 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
18d80 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 ],.** and/or [SQ
18d90 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
18da0 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e ECACHE] flags:)^
18db0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e .**.** <dl>.** ^
18dc0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
18dd0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e N_READONLY]</dt>
18de0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
18df0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 base is opened i
18e00 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 n read-only mode
18e10 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 . If the databa
18e20 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 se does not.** a
18e30 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e lready exist, an
18e40 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
18e50 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a ed.</dd>)^.**.**
18e60 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
18e70 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f PEN_READWRITE]</
18e80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
18e90 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
18ea0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e d for reading an
18eb0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 d writing if pos
18ec0 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e sible, or readin
18ed0 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 g.** only if the
18ee0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 file is write p
18ef0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 rotected by the
18f00 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
18f10 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 . In either.**
18f20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 case the databas
18f30 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 e must already e
18f40 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 xist, otherwise
18f50 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
18f60 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a rned.</dd>)^.**.
18f70 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
18f80 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
18f90 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f | [SQLITE_OPEN_
18fa0 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 CREATE]</dt>.**
18fb0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
18fc0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
18fd0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 eading and writi
18fe0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 ng, and is creat
18ff0 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 es it if.** it d
19000 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 oes not already
19010 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 exist. This is t
19020 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 he behavior that
19030 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 is always used
19040 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
19050 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
19060 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 3_open16().</dd>
19070 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a )^.** </dl>.**.*
19080 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 * If the 3rd par
19090 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
190a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 3_open_v2() is n
190b0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a ot one of the.**
190c0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 combinations sh
190d0 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 own above or one
190e0 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 of the combinat
190f0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 ions shown above
19100 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 combined.** wit
19110 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 h the [SQLITE_OP
19120 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 EN_NOMUTEX], [SQ
19130 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
19140 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 TEX],.** [SQLITE
19150 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
19160 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 E] and/or [SQLIT
19170 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
19180 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 HE] flags,.** th
19190 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
191a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
191b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c .** ^If the [SQL
191c0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
191d0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 ] flag is set, t
191e0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
191f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f connection.** o
19200 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 pens in the mult
19210 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 i-thread [thread
19220 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e ing mode] as lon
19230 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d g as the single-
19240 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 thread.** mode h
19250 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 as not been set
19260 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
19270 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 or start-time.
19280 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ^If the.** [SQLI
19290 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
192a0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 X] flag is set t
192b0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
192c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e connection open
192d0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 s.** in the seri
192e0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
192f0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 g mode] unless s
19300 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 ingle-thread was
19310 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
19320 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 elected at compi
19330 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
19340 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b -time..** ^The [
19350 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
19360 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 EDCACHE] flag ca
19370 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 uses the databas
19380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 e connection to
19390 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 be.** eligible t
193a0 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 o use [shared ca
193b0 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 che mode], regar
193c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
193d0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a or not shared.*
193e0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c * cache is enabl
193f0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
19400 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 3_enable_shared_
19410 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a cache()]. ^The.
19420 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
19430 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c PRIVATECACHE] fl
19440 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 ag causes the da
19450 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
19460 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 n to not.** part
19470 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 icipate in [shar
19480 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 ed cache mode] e
19490 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 ven if it is ena
194a0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 bled..**.** ^If
194b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
194c0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e ":memory:", then
194d0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 a private, temp
194e0 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 orary in-memory
194f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 database.** is c
19500 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 reated for the c
19510 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 onnection. ^Thi
19520 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 s in-memory data
19530 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 base will vanish
19540 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 when.** the dat
19550 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19560 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 is closed. Fut
19570 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
19580 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 SQLite might.**
19590 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 make use of addi
195a0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 tional special f
195b0 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 ilenames that be
195c0 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 gin with the ":"
195d0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 character..** I
195e0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
195f0 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 that when a dat
19600 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 abase filename a
19610 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 ctually does beg
19620 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 in with.** a ":"
19630 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 character you s
19640 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 hould prefix the
19650 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 filename with a
19660 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 pathname such a
19670 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f s.** "./" to avo
19680 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a id ambiguity..**
19690 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 .** ^If the file
196a0 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 name is an empty
196b0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 string, then a
196c0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 private, tempora
196d0 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 ry.** on-disk da
196e0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 tabase will be c
196f0 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 reated. ^This p
19700 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 rivate database
19710 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d will be.** autom
19720 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 atically deleted
19730 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 as soon as the
19740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
19750 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
19760 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
19770 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
19780 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
19790 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
197a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 he.** [sqlite3_v
197b0 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 fs] object that
197c0 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 defines the oper
197d0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 ating system int
197e0 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 erface that.** t
197f0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 he new database
19800 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c connection shoul
19810 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 d use. ^If the
19820 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
19830 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f is.** a NULL po
19840 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 inter then the d
19850 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
19860 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 vfs] object is u
19870 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f sed..**.** <b>No
19880 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 te to Windows us
19890 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e ers:</b> The en
198a0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 coding used for
198b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 the filename arg
198c0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 ument.** of sqli
198d0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
198e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
198f0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 must be UTF-8,
19900 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 not whatever.**
19910 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 codepage is curr
19920 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 ently defined.
19930 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 Filenames contai
19940 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e ning internation
19950 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 al.** characters
19960 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
19970 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f ed to UTF-8 prio
19980 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 r to passing the
19990 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 m into.** sqlite
199a0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
199b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a te3_open_v2()..*
199c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 /.int sqlite3_op
199d0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 en(. const char
199e0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
199f0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
19a00 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 me (UTF-8) */.
19a10 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
19a20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
19a30 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
19a40 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
19a50 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e e3_open16(. con
19a60 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d st void *filenam
19a70 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 e, /* Database
19a80 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 filename (UTF-1
19a90 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 6) */. sqlite3
19aa0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
19ab0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
19ac0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 b handle */.);.i
19ad0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nt sqlite3_open_
19ae0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 v2(. const char
19af0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
19b00 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
19b10 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 me (UTF-8) */.
19b20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 sqlite3 **ppDb,
19b30 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
19b40 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
19b50 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c */. int flags,
19b60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
19b70 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 Flags */. cons
19b80 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 t char *zVfs
19b90 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 /* Name of V
19ba0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 FS module to use
19bb0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
19bc0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f PI3REF: Error Co
19bd0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 des And Messages
19be0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
19bf0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e te3_errcode() in
19c00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
19c10 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 the numeric [res
19c20 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 ult code] or.**
19c30 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
19c40 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d code] for the m
19c50 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 ost recent faile
19c60 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 d sqlite3_* API
19c70 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 call.** associat
19c80 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 ed with a [datab
19c90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
19ca0 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 If a prior API
19cb0 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 call failed.** b
19cc0 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 ut the most rece
19cd0 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 nt API call succ
19ce0 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 eeded, the retur
19cf0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 n value from.**
19d00 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
19d10 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 ) is undefined.
19d20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
19d30 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
19d40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
19d50 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 the same except
19d60 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 that it always
19d70 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 returns the .**
19d80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
19d90 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e code] even when
19da0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
19db0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 codes are.** di
19dc0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 sabled..**.** ^T
19dd0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 he sqlite3_errms
19de0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f g() and sqlite3_
19df0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 errmsg16() retur
19e00 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 n English-langua
19e10 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 ge.** text that
19e20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
19e30 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 ror, as either U
19e40 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
19e50 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
19e60 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 ^(Memory to hold
19e70 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
19e80 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
19e90 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e aged internally.
19ea0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
19eb0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ion does not nee
19ec0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 d to worry about
19ed0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 freeing the res
19ee0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ult..** However,
19ef0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e the error strin
19f00 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 g might be overw
19f10 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f ritten or deallo
19f20 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 cated by.** subs
19f30 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
19f40 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
19f50 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 erface functions
19f60 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 .)^.**.** When t
19f70 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 he serialized [t
19f80 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 hreading mode] i
19f90 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 s in use, it mig
19fa0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 ht be the.** cas
19fb0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 e that a second
19fc0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 error occurs on
19fd0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
19fe0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 d in between.**
19ff0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 the time of the
1a000 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 first error and
1a010 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 the call to thes
1a020 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a e interfaces..**
1a030 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 When that happe
1a040 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 ns, the second e
1a050 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 rror will be rep
1a060 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 orted since thes
1a070 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 e.** interfaces
1a080 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 always report th
1a090 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 e most recent re
1a0a0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a sult. To avoid.
1a0b0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 ** this, each th
1a0c0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 read can obtain
1a0d0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 exclusive use of
1a0e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
1a0f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 onnection] D.**
1a100 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c by invoking [sql
1a110 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
1a120 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 ]([sqlite3_db_mu
1a130 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 tex](D)) before
1a140 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 beginning.** to
1a150 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 use D and invoki
1a160 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ng [sqlite3_mute
1a170 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 x_leave]([sqlite
1a180 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 3_db_mutex](D))
1a190 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c after.** all cal
1a1a0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 ls to the interf
1a1b0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 aces listed here
1a1c0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a are completed..
1a1d0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 **.** If an inte
1a1e0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 rface fails with
1a1f0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 SQLITE_MISUSE,
1a200 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 that means the i
1a210 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 nterface.** was
1a220 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 invoked incorrec
1a230 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 tly by the appli
1a240 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 cation. In that
1a250 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 case, the.** er
1a260 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 ror code and mes
1a270 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 sage may or may
1a280 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 not be set..*/.i
1a290 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f nt sqlite3_errco
1a2a0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
1a2b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 .int sqlite3_ext
1a2c0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 ended_errcode(sq
1a2d0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 lite3 *db);.cons
1a2e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
1a2f0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 errmsg(sqlite3*)
1a300 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
1a310 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 lite3_errmsg16(s
1a320 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
1a330 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 CAPI3REF: SQL S
1a340 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
1a350 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
1a360 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1a370 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 } {prepared stat
1a380 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e ements}.**.** An
1a390 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
1a3a0 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
1a3b0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c nts a single SQL
1a3c0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 statement..** T
1a3d0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 his object is va
1a3e0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 riously known as
1a3f0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 a "prepared sta
1a400 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 tement" or a.**
1a410 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 "compiled SQL st
1a420 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 atement" or simp
1a430 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 ly as a "stateme
1a440 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c nt"..**.** The l
1a450 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 ife of a stateme
1a460 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 nt object goes s
1a470 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 omething like th
1a480 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a is:.**.** <ol>.*
1a490 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 * <li> Create th
1a4a0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
1a4b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1a4c0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 v2()] or a relat
1a4d0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 ed.** funct
1a4e0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e ion..** <li> Bin
1a4f0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 d values to [hos
1a500 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 t parameters] us
1a510 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
1a520 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 bind_*().**
1a530 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
1a540 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c <li> Run the SQL
1a550 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
1a560 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 ite3_step()] one
1a570 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
1a580 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 ** <li> Reset th
1a590 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e e statement usin
1a5a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
1a5b0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b ()] then go back
1a5c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 .** to step
1a5d0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 2. Do this zer
1a5e0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e o or more times.
1a5f0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 .** <li> Destroy
1a600 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
1a610 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
1a620 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e ize()]..** </ol>
1a630 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 .**.** Refer to
1a640 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e documentation on
1a650 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 individual meth
1a660 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 ods above for ad
1a670 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f ditional.** info
1a680 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 rmation..*/.type
1a690 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
1a6a0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f e3_stmt sqlite3_
1a6b0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 stmt;../*.** CAP
1a6c0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 I3REF: Run-time
1a6d0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 Limits.**.** ^(T
1a6e0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
1a6f0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 lows the size of
1a700 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 various constru
1a710 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 cts to be limite
1a720 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 d.** on a connec
1a730 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 tion by connecti
1a740 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 on basis. The f
1a750 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
1a760 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 s the.** [databa
1a770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 se connection] w
1a780 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f hose limit is to
1a790 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 be set or queri
1a7a0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f ed. The.** seco
1a7b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
1a7c0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 one of the [limi
1a7d0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 t categories] th
1a7e0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 at define a.** c
1a7f0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 lass of construc
1a800 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 ts to be size li
1a810 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 mited. The thir
1a820 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
1a830 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 he.** new limit
1a840 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 for that constru
1a850 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f ct. The functio
1a860 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c n returns the ol
1a870 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a 2a d limit.)^.**.**
1a880 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d ^If the new lim
1a890 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 it is a negative
1a8a0 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d number, the lim
1a8b0 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e it is unchanged.
1a8c0 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65 20 6c 69 .** ^(For the li
1a8d0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 mit category of
1a8e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a SQLITE_LIMIT_XYZ
1a8f0 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 there is a .**
1a900 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 [limits | hard u
1a910 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 pper bound].** s
1a920 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d et by a compile-
1a930 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 time C preproces
1a940 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 sor macro named
1a950 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 .** [limits | SQ
1a960 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a LITE_MAX_XYZ]..*
1a970 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 * (The "_LIMIT_"
1a980 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 in the name is
1a990 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 changed to "_MAX
1a9a0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d _".))^.** ^Attem
1a9b0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 pts to increase
1a9c0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 a limit above it
1a9d0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 s hard upper bou
1a9e0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 nd are.** silent
1a9f0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 ly truncated to
1aa00 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c the hard upper l
1aa10 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d imit..**.** Run-
1aa20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 time limits are
1aa30 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
1aa40 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 in applications
1aa50 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 that manage.**
1aa60 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 both their own i
1aa70 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
1aa80 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 and also databa
1aa90 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e ses that are con
1aaa0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e trolled.** by un
1aab0 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c trusted external
1aac0 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 sources. An ex
1aad0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f ample applicatio
1aae0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 n might be a.**
1aaf0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 web browser that
1ab00 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 has its own dat
1ab10 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 abases for stori
1ab20 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a ng history and.*
1ab30 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 * separate datab
1ab40 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 ases controlled
1ab50 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 by JavaScript ap
1ab60 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c plications downl
1ab70 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 oaded.** off the
1ab80 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 Internet. The
1ab90 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
1aba0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 es can be given
1abb0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 the.** large, de
1abc0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 fault limits. D
1abd0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 atabases managed
1abe0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 by external sou
1abf0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 rces can.** be g
1ac00 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 iven much smalle
1ac10 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 r limits designe
1ac20 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 d to prevent a d
1ac30 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 enial of service
1ac40 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 .** attack. Dev
1ac50 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c elopers might al
1ac60 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 so want to use t
1ac70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
1ac80 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a authorizer()].**
1ac90 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 interface to fu
1aca0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e rther control un
1acb0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 trusted SQL. Th
1acc0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 e size of the da
1acd0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 tabase.** create
1ace0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 d by an untruste
1acf0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 d script can be
1ad00 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 contained using
1ad10 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 the.** [max_page
1ad20 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
1ad30 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d ..**.** New run-
1ad40 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 time limit categ
1ad50 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 ories may be add
1ad60 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
1ad70 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 eases..*/.int sq
1ad80 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 lite3_limit(sqli
1ad90 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e te3*, int id, in
1ada0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a t newVal);../*.*
1adb0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
1adc0 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 Time Limit Categ
1add0 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ories.** KEYWORD
1ade0 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f S: {limit catego
1adf0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 ry} {*limit cate
1ae00 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 gories}.**.** Th
1ae10 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ese constants de
1ae20 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 fine various per
1ae30 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a formance limits.
1ae40 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c ** that can be l
1ae50 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 owered at run-ti
1ae60 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 me using [sqlite
1ae70 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 3_limit()]..** T
1ae80 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 he synopsis of t
1ae90 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
1aea0 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 he various limit
1aeb0 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 s is shown below
1aec0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
1aed0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 information is a
1aee0 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d vailable at [lim
1aef0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 its | Limits in
1af00 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c SQLite]..**.** <
1af10 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c dl>.** ^(<dt>SQL
1af20 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
1af30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1af40 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 maximum size of
1af50 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 any string or B
1af60 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 LOB or table row
1af70 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 .<dd>)^.**.** ^(
1af80 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
1af90 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e _SQL_LENGTH</dt>
1afa0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1afb0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e mum length of an
1afc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c SQL statement.<
1afd0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c /dd>)^.**.** ^(<
1afe0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1aff0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c COLUMN</dt>.** <
1b000 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
1b010 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
1b020 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 in a table defi
1b030 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 nition or in the
1b040 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f .** result set o
1b050 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 f a [SELECT] or
1b060 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
1b070 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
1b080 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 an index.** or
1b090 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f in an ORDER BY o
1b0a0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 r GROUP BY claus
1b0b0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 e.</dd>)^.**.**
1b0c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
1b0d0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 IT_EXPR_DEPTH</d
1b0e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1b0f0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 ximum depth of t
1b100 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e he parse tree on
1b110 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e any expression.
1b120 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 </dd>)^.**.** ^(
1b130 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
1b140 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
1b150 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1b160 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1b170 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f of terms in a co
1b180 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 mpound SELECT st
1b190 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a atement.</dd>)^.
1b1a0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 **.** ^(<dt>SQLI
1b1b0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 TE_LIMIT_VDBE_OP
1b1c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1b1d0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1b1e0 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 of instructions
1b1f0 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 in a virtual mac
1b200 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 hine program.**
1b210 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
1b220 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 t an SQL stateme
1b230 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a nt.</dd>)^.**.**
1b240 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
1b250 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
1b260 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1b270 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1b280 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 of arguments on
1b290 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e a function.</dd>
1b2a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 )^.**.** ^(<dt>S
1b2b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
1b2c0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 CHED</dt>.** <dd
1b2d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
1b2e0 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c ber of [ATTACH |
1b2f0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
1b300 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ses].</dd>.**.**
1b310 20 5e 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^<dt>SQLITE_LIM
1b320 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
1b330 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
1b340 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c dd>The maximum l
1b350 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 ength of the pat
1b360 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f tern argument to
1b370 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a the [LIKE] or.*
1b380 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f * [GLOB] operato
1b390 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a rs.</dd>)^.**.**
1b3a0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
1b3b0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
1b3c0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e BER</dt>.** <dd>
1b3d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1b3e0 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 er of variables
1b3f0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d in an SQL statem
1b400 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 ent that can.**
1b410 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29 5e be bound.</dd>)^
1b420 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c .**.** ^(<dt>SQL
1b430 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 ITE_LIMIT_TRIGGE
1b440 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 R_DEPTH</dt>.**
1b450 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
1b460 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 depth of recursi
1b470 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e on for triggers.
1b480 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e </dd>)^.** </dl>
1b490 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
1b4a0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 TE_LIMIT_LENGTH
1b4b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1b4c0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
1b4d0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
1b4e0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 NGTH
1b4f0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
1b500 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
1b510 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 N
1b520 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
1b530 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 QLITE_LIMIT_EXPR
1b540 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 _DEPTH
1b550 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
1b560 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d SQLITE_LIMIT_COM
1b570 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 POUND_SELECT
1b580 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
1b590 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 SQLITE_LIMIT_VD
1b5a0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 BE_OP
1b5b0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
1b5c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 e SQLITE_LIMIT_F
1b5d0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 UNCTION_ARG
1b5e0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
1b5f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
1b600 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 ATTACHED
1b610 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 7.#def
1b620 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
1b630 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
1b640 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 NGTH 8.#de
1b650 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
1b660 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
1b670 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 R 9.#d
1b680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
1b690 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 IT_TRIGGER_DEPTH
1b6a0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 10..
1b6b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1b6c0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c Compiling An SQL
1b6d0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 Statement.** KE
1b6e0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 YWORDS: {SQL sta
1b6f0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d tement compiler}
1b700 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 .**.** To execut
1b710 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 e an SQL query,
1b720 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 it must first be
1b730 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 compiled into a
1b740 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 byte-code.** pr
1b750 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 ogram using one
1b760 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
1b770 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
1b780 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 st argument, "db
1b790 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 ", is a [databas
1b7a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 e connection] ob
1b7b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a tained from a.**
1b7c0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
1b7d0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
1b7e0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
1b7f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
1b800 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f or.** [sqlite3_o
1b810 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 pen16()]. The d
1b820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1b830 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 on must not have
1b840 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a been closed..**
1b850 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
1b860 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c rgument, "zSql",
1b870 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
1b880 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
1b890 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
1b8a0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
1b8b0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
1b8c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
1b8d0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
1b8e0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
1b8f0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c faces use UTF-8,
1b900 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
1b910 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
1b920 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1b930 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
1b940 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 6..**.** ^If the
1b950 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 nByte argument
1b960 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 is less than zer
1b970 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 o, then zSql is
1b980 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a read up to the.*
1b990 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 * first zero ter
1b9a0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 minator. ^If nBy
1b9b0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 te is non-negati
1b9c0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 ve, then it is t
1b9d0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 he maximum.** nu
1b9e0 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 mber of bytes r
1b9f0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 ead from zSql.
1ba00 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e ^When nByte is n
1ba10 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
1ba20 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 .** zSql string
1ba30 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 ends at either t
1ba40 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 he first '\000'
1ba50 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 or '\u0000' char
1ba60 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 acter or.** the
1ba70 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 nByte-th byte, w
1ba80 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 hichever comes f
1ba90 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c irst. If the cal
1baa0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 ler knows.** tha
1bab0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 t the supplied s
1bac0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 tring is nul-ter
1bad0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 minated, then th
1bae0 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a ere is a small.*
1baf0 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 * performance ad
1bb00 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 vantage to be ga
1bb10 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 ined by passing
1bb20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 an nByte paramet
1bb30 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 er that.** is eq
1bb40 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 ual to the numbe
1bb50 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
1bb60 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c e input string <
1bb70 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a i>including</i>.
1bb80 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 ** the nul-termi
1bb90 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a nator bytes..**.
1bba0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 ** ^If pzTail is
1bbb0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a not NULL then *
1bbc0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 pzTail is made t
1bbd0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 o point to the f
1bbe0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 irst byte.** pas
1bbf0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 t the end of the
1bc00 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 first SQL state
1bc10 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 ment in zSql. T
1bc20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
1bc30 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 ly.** compile th
1bc40 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e e first statemen
1bc50 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 t in zSql, so *p
1bc60 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f zTail is left po
1bc70 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 inting to.** wha
1bc80 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 t remains uncomp
1bc90 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 iled..**.** ^*pp
1bca0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 Stmt is left poi
1bcb0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 nting to a compi
1bcc0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 led [prepared st
1bcd0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 atement] that ca
1bce0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 n be.** executed
1bcf0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1bd00 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 step()]. ^If th
1bd10 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c ere is an error,
1bd20 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a *ppStmt is set.
1bd30 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 ** to NULL. ^If
1bd40 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 the input text
1bd50 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 contains no SQL
1bd60 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 (if the input is
1bd70 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 an empty.** str
1bd80 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 ing or a comment
1bd90 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 ) then *ppStmt i
1bda0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a s set to NULL..*
1bdb0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 * The calling pr
1bdc0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f ocedure is respo
1bdd0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 nsible for delet
1bde0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 ing the compiled
1bdf0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
1be00 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
1be10 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 _finalize()] aft
1be20 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 er it has finish
1be30 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 ed with it..** p
1be40 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 pStmt may not be
1be50 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e NULL..**.** ^On
1be60 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 success, the sq
1be70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 lite3_prepare()
1be80 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e family of routin
1be90 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 es return [SQLIT
1bea0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 E_OK];.** otherw
1beb0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ise an [error co
1bec0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
1bed0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
1bee0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 e3_prepare_v2()
1bef0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
1bf00 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 are16_v2() inter
1bf10 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 faces are.** rec
1bf20 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c ommended for all
1bf30 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 new programs. T
1bf40 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 he two older int
1bf50 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 erfaces are reta
1bf60 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b ined.** for back
1bf70 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
1bf80 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 ity, but their u
1bf90 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 se is discourage
1bfa0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 d..** ^In the "v
1bfb0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 2" interfaces, t
1bfc0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
1bfd0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 ement.** that is
1bfe0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b returned (the [
1bff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
1c000 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 ject) contains a
1c010 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
1c020 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 original SQL tex
1c030 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 t. This causes t
1c040 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
1c050 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f ()] interface to
1c060 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 .** behave diffe
1c070 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 rently in three
1c080 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e ways:.**.** <ol>
1c090 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 .** <li>.** ^If
1c0a0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 the database sch
1c0b0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 ema changes, ins
1c0c0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e tead of returnin
1c0d0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 g [SQLITE_SCHEMA
1c0e0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 ] as it.** alway
1c0f0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 s used to do, [s
1c100 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
1c110 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ill automaticall
1c120 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 y recompile the
1c130 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 SQL.** statement
1c140 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 and try to run
1c150 69 74 20 61 67 61 69 6e 2e 20 20 5e 49 66 20 74 it again. ^If t
1c160 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 he schema has ch
1c170 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 anged in.** a wa
1c180 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 y that makes the
1c190 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f statement no lo
1c1a0 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c nger valid, [sql
1c1b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
1c1c0 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 l still.** retur
1c1d0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 n [SQLITE_SCHEMA
1c1e0 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 ]. But unlike t
1c1f0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
1c200 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 or, [SQLITE_SCHE
1c210 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 MA] is.** now a
1c220 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 fatal error. Ca
1c230 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 lling [sqlite3_p
1c240 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 repare_v2()] aga
1c250 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 in will not make
1c260 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f the.** error go
1c270 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 away. Note: us
1c280 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 e [sqlite3_errms
1c290 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 g()] to find the
1c2a0 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 text.** of the
1c2b0 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 parsing error th
1c2c0 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e at results in an
1c2d0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
1c2e0 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 return..** </li
1c2f0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
1c300 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f ^When an error o
1c310 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
1c320 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
1c330 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
1c340 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
1c350 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
1c360 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
1c370 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 s]. ^The legacy
1c380 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 behavior was th
1c390 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 at.** [sqlite3_s
1c3a0 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c tep()] would onl
1c3b0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 y return a gener
1c3c0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ic [SQLITE_ERROR
1c3d0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a ] result code.**
1c3e0 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 and you would h
1c3f0 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 ave to make a se
1c400 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cond call to [sq
1c410 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 lite3_reset()] i
1c420 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 n order.** to fi
1c430 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
1c440 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 g cause of the p
1c450 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 roblem. With the
1c460 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a "v2" prepare.**
1c470 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
1c480 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 underlying reas
1c490 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 on for the error
1c4a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
1c4b0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c ediately..** </l
1c4c0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
1c4d0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f ^If the value o
1c4e0 66 20 61 20 5b 70 61 72 61 6d 65 74 65 72 20 7c f a [parameter |
1c4f0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d host parameter]
1c500 20 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c in the WHERE cl
1c510 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68 ause might.** ch
1c520 61 6e 67 65 20 74 68 65 20 71 75 65 72 79 20 70 ange the query p
1c530 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d lan for a statem
1c540 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 73 74 ent, then the st
1c550 61 74 65 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a atement may be.*
1c560 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
1c570 72 65 63 6f 6d 70 69 6c 65 64 20 28 61 73 20 69 recompiled (as i
1c580 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e f there had been
1c590 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
1c5a0 29 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 0a ) on the first .
1c5b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
1c5c0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 ()] call followi
1c5d0 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 20 74 6f ng any change to
1c5e0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
1c5f0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 3_bind_text | bi
1c600 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b ndings] of the [
1c610 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 parameter]. .**
1c620 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a </li>.** </ol>.*
1c630 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 /.int sqlite3_pr
1c640 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 epare(. sqlite3
1c650 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
1c660 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
1c670 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
1c680 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 har *zSql,
1c690 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
1c6a0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 t, UTF-8 encoded
1c6b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
1c6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
1c6d0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
1c6e0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
1c6f0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
1c700 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
1c710 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
1c720 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
1c730 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
1c740 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
1c750 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
1c760 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
1c770 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
1c780 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 _prepare_v2(. s
1c790 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
1c7a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
1c7b0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
1c7c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
1c7d0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
1c7e0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
1c7f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
1c800 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
1c810 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
1c820 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
1c830 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
1c840 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
1c850 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
1c860 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
1c870 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
1c880 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
1c890 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
1c8a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
1c8b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 zSql */.);.int s
1c8c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1c8d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
1c8e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
1c8f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
1c900 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
1c910 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
1c920 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
1c930 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a F-16 encoded */.
1c940 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
1c950 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
1c960 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
1c970 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
1c980 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
1c990 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
1c9a0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
1c9b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
1c9c0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
1c9d0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
1c9e0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
1c9f0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
1ca00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
1ca10 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c pare16_v2(. sql
1ca20 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
1ca30 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
1ca40 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
1ca50 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
1ca60 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
1ca70 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
1ca80 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
1ca90 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
1caa0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
1cab0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
1cac0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
1cad0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
1cae0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
1caf0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
1cb00 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 const void **p
1cb10 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
1cb20 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
1cb30 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
1cb40 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a Sql */.);../*.**
1cb50 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 CAPI3REF: Retri
1cb60 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 eving Statement
1cb70 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 SQL.**.** ^This
1cb80 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
1cb90 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
1cba0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f e a saved copy o
1cbb0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a f the original.*
1cbc0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
1cbd0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 to create a [pre
1cbe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1cbf0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 if that stateme
1cc00 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c nt was.** compil
1cc10 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
1cc20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1cc30 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
1cc40 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1cc50 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 )]..*/.const cha
1cc60 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
1cc70 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
1cc80 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
1cc90 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 3REF: Dynamicall
1cca0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 y Typed Value Ob
1ccb0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ject.** KEYWORDS
1ccc0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c : {protected sql
1ccd0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 ite3_value} {unp
1cce0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1ccf0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 _value}.**.** SQ
1cd00 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 Lite uses the sq
1cd10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1cd20 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 ct to represent
1cd30 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 all values.** th
1cd40 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 at can be stored
1cd50 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 in a database t
1cd60 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 able. SQLite use
1cd70 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 s dynamic typing
1cd80 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 .** for the valu
1cd90 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e es it stores. ^
1cda0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e Values stored in
1cdb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1cdc0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 bjects.** can be
1cdd0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 integers, float
1cde0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 ing point values
1cdf0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 , strings, BLOBs
1ce00 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a , or NULL..**.**
1ce10 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 An sqlite3_valu
1ce20 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 e object may be
1ce30 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 either "protecte
1ce40 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 d" or "unprotect
1ce50 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 ed"..** Some int
1ce60 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
1ce70 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
1ce80 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 te3_value. Othe
1ce90 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 r interfaces.**
1cea0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 will accept eith
1ceb0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f er a protected o
1cec0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 r an unprotected
1ced0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
1cee0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 ** Every interfa
1cef0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 ce that accepts
1cf00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 sqlite3_value ar
1cf10 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 guments specifie
1cf20 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 s.** whether or
1cf30 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 not it requires
1cf40 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
1cf50 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a te3_value..**.**
1cf60 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 The terms "prot
1cf70 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 ected" and "unpr
1cf80 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 otected" refer t
1cf90 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 o whether or not
1cfa0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 .** a mutex is h
1cfb0 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c eld. A internal
1cfc0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
1cfd0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a or a protected.*
1cfe0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1cff0 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 object but no mu
1d000 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
1d010 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a an unprotected.*
1d020 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1d030 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 object. If SQLi
1d040 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 te is compiled t
1d050 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 o be single-thre
1d060 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 aded.** (with [S
1d070 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1d080 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 =0] and with [sq
1d090 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
1d0a0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 ()] returning 0)
1d0b0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 .** or if SQLite
1d0c0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f is run in one o
1d0d0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 f reduced mutex
1d0e0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 modes .** [SQLIT
1d0f0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
1d100 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 HREAD] or [SQLIT
1d110 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
1d120 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 READ].** then th
1d130 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e ere is no distin
1d140 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
1d150 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
1d160 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
1d170 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1d180 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 and they can be
1d190 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 used interchang
1d1a0 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c eably. However,
1d1b0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 .** for maximum
1d1c0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 code portability
1d1d0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 it is recommend
1d1e0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 ed that applicat
1d1f0 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 ions.** still ma
1d200 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 ke the distincti
1d210 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 on between betwe
1d220 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
1d230 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
1d240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1d250 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 jects even when
1d260 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 not strictly req
1d270 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 uired..**.** ^Th
1d280 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
1d290 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 objects that are
1d2a0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d passed as param
1d2b0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a eters into the.*
1d2c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
1d2d0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e of [application
1d2e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
1d2f0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 ctions] are prot
1d300 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 ected..** ^The s
1d310 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1d320 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
1d330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
1d340 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
1d350 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 nprotected..** U
1d360 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
1d370 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1d380 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 may only be use
1d390 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 d with.** [sqlit
1d3a0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
1d3b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1d3c0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a bind_value()]..*
1d3d0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 * The [sqlite3_v
1d3e0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 alue_blob | sqli
1d3f0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 te3_value_type()
1d400 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 ] family of.** i
1d410 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 nterfaces requir
1d420 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 e protected sqli
1d430 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1d440 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 s..*/.typedef st
1d450 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 ruct Mem sqlite3
1d460 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _value;../*.** C
1d470 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e API3REF: SQL Fun
1d480 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 ction Context Ob
1d490 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ject.**.** The c
1d4a0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 ontext in which
1d4b0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 an SQL function
1d4c0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 executes is stor
1d4d0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 ed in an.** sqli
1d4e0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
1d4f0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 ct. ^A pointer
1d500 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f to an sqlite3_co
1d510 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 ntext object.**
1d520 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 is always first
1d530 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 parameter to [ap
1d540 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
1d550 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
1d560 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
1d570 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
1d580 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
1d590 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 entation will pa
1d5a0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 ss this.** point
1d5b0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 er through into
1d5c0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
1d5d0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 3_result_int | s
1d5e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d qlite3_result()]
1d5f0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 ,.** [sqlite3_ag
1d600 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
1d610 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 )], [sqlite3_use
1d620 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 r_data()],.** [s
1d630 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
1d640 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 b_handle()], [sq
1d650 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
1d660 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 a()],.** and/or
1d670 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 [sqlite3_set_aux
1d680 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 data()]..*/.type
1d690 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
1d6a0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 e3_context sqlit
1d6b0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a e3_context;../*.
1d6c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e ** CAPI3REF: Bin
1d6d0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 ding Values To P
1d6e0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
1d6f0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ts.** KEYWORDS:
1d700 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d {host parameter}
1d710 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
1d720 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 s} {host paramet
1d730 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 er name}.** KEYW
1d740 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d ORDS: {SQL param
1d750 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d eter} {SQL param
1d760 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 eters} {paramete
1d770 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a r binding}.**.**
1d780 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 ^(In the SQL st
1d790 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 atement text inp
1d7a0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 ut to [sqlite3_p
1d7b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
1d7c0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a its variants,.*
1d7d0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 * literals may b
1d7e0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 e replaced by a
1d7f0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 [parameter] that
1d800 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 matches one of
1d810 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d following.** tem
1d820 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 plates:.**.** <u
1d830 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a l>.** <li> ?.**
1d840 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c <li> ?NNN.** <
1d850 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 li> :VVV.** <li
1d860 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > @VVV.** <li>
1d870 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a $VVV.** </ul>.*
1d880 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 *.** In the temp
1d890 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e lates above, NNN
1d8a0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 represents an i
1d8b0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a nteger literal,.
1d8c0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 ** and VVV repre
1d8d0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 sents an alphanu
1d8e0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e meric identifer.
1d8f0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 )^ ^The values
1d900 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 of these.** para
1d910 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c meters (also cal
1d920 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 led "host parame
1d930 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 ter names" or "S
1d940 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a QL parameters").
1d950 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 ** can be set us
1d960 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
1d970 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1d980 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a s defined here..
1d990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
1d9a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
1d9b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
1d9c0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c ) routines is al
1d9d0 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 ways.** a pointe
1d9e0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
1d9f0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 3_stmt] object r
1da00 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 eturned from.**
1da10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1da20 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 _v2()] or its va
1da30 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 riants..**.** ^T
1da40 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
1da50 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
1da60 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d of the SQL param
1da70 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a eter to be set..
1da80 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 ** ^The leftmost
1da90 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 SQL parameter h
1daa0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
1dab0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d . ^When the sam
1dac0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 e named.** SQL p
1dad0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 arameter is used
1dae0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c more than once,
1daf0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
1db00 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 equent.** occurr
1db10 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 ences have the s
1db20 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 ame index as the
1db30 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 first occurrenc
1db40 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 e..** ^The index
1db50 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d for named param
1db60 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f eters can be loo
1db70 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 ked up using the
1db80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
1db90 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
1dba0 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 x()] API if desi
1dbb0 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 red. ^The index
1dbc0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 .** for "?NNN" p
1dbd0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 arameters is the
1dbe0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a value of NNN..*
1dbf0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 * ^The NNN value
1dc00 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e must be between
1dc10 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 1 and the [sqli
1dc20 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 te3_limit()].**
1dc30 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 parameter [SQLIT
1dc40 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
1dc50 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c _NUMBER] (defaul
1dc60 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a t value: 999)..*
1dc70 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
1dc80 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
1dc90 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f value to bind to
1dca0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
1dcb0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 **.** ^(In those
1dcc0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 routines that h
1dcd0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 ave a fourth arg
1dce0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 ument, its value
1dcf0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
1dd00 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
1dd10 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f e parameter. To
1dd20 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 be clear: the v
1dd30 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
1dd40 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 umber of <u>byte
1dd50 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c s</u> in the val
1dd60 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ue, not the numb
1dd70 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
1dd80 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .)^.** ^If the f
1dd90 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
1dda0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
1ddb0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 length of the s
1ddc0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 tring is.** the
1ddd0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
1dde0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
1ddf0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
1de00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 .**.** ^The fift
1de10 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 h argument to sq
1de20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
1de30 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ), sqlite3_bind_
1de40 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 text(), and.** s
1de50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
1de60 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 16() is a destru
1de70 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 ctor used to dis
1de80 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 pose of the BLOB
1de90 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 or.** string af
1dea0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 ter SQLite has f
1deb0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
1dec0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 ^If the fifth a
1ded0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 rgument is.** th
1dee0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 e special value
1def0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c [SQLITE_STATIC],
1df00 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 then SQLite ass
1df10 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
1df20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
1df30 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e in static, unman
1df40 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 aged space and d
1df50 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
1df60 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 be freed..** ^If
1df70 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
1df80 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 ent has the valu
1df90 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 e [SQLITE_TRANSI
1dfa0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 ENT], then.** SQ
1dfb0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f Lite makes its o
1dfc0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
1dfd0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 of the data imme
1dfe0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a diately, before.
1dff0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ** the sqlite3_b
1e000 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 ind_*() routine
1e010 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e returns..**.** ^
1e020 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
1e030 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 _zeroblob() rout
1e040 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 ine binds a BLOB
1e050 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 of length N tha
1e060 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 t.** is filled w
1e070 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 ith zeroes. ^A
1e080 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 zeroblob uses a
1e090 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 fixed amount of
1e0a0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 memory.** (just
1e0b0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f an integer to ho
1e0c0 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 ld its size) whi
1e0d0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 le it is being p
1e0e0 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 rocessed..** Zer
1e0f0 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e oblobs are inten
1e100 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 ded to serve as
1e110 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 placeholders for
1e120 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 BLOBs whose.**
1e130 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 content is later
1e140 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a written using.*
1e150 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f * [sqlite3_blob_
1e160 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 open | increment
1e170 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 al BLOB I/O] rou
1e180 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 tines..** ^A neg
1e190 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 ative value for
1e1a0 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 the zeroblob res
1e1b0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c ults in a zero-l
1e1c0 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a ength BLOB..**.*
1e1d0 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 * ^If any of the
1e1e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
1e1f0 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 ) routines are c
1e200 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c alled with a NUL
1e210 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 L pointer.** for
1e220 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
1e230 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 tatement] or wit
1e240 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 h a prepared sta
1e250 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 tement for which
1e260 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
1e270 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 p()] has been ca
1e280 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 lled more recent
1e290 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 ly than [sqlite3
1e2a0 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 _reset()],.** th
1e2b0 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c en the call will
1e2c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1e2d0 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 MISUSE]. If any
1e2e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 sqlite3_bind_()
1e2f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 .** routine is p
1e300 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 assed a [prepare
1e310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
1e320 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c t has been final
1e330 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 ized, the.** res
1e340 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ult is undefined
1e350 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 and probably ha
1e360 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 rmful..**.** ^Bi
1e370 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 ndings are not c
1e380 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 leared by the [s
1e390 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1e3a0 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 routine..** ^Unb
1e3b0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 ound parameters
1e3c0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 are interpreted
1e3d0 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e as NULL..**.** ^
1e3e0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
1e3f0 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 _* routines retu
1e400 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
1e410 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a n success or an.
1e420 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ** [error code]
1e430 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 if anything goes
1e440 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c wrong..** ^[SQL
1e450 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 ITE_RANGE] is re
1e460 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 turned if the pa
1e470 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 rameter.** index
1e480 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1e490 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 . ^[SQLITE_NOME
1e4a0 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 M] is returned i
1e4b0 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 f malloc() fails
1e4c0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
1e4d0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
1e4e0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
1e4f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
1e500 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
1e510 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c ame()], and [sql
1e520 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1e530 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
1e540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
1e550 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 d_blob(sqlite3_s
1e560 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
1e570 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 void*, int n, v
1e580 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
1e590 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
1e5a0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
1e5b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 stmt*, int, doub
1e5c0 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 le);.int sqlite3
1e5d0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 _bind_int(sqlite
1e5e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
1e5f0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f t);.int sqlite3_
1e600 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 bind_int64(sqlit
1e610 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 e3_stmt*, int, s
1e620 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 qlite3_int64);.i
1e630 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1e640 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d null(sqlite3_stm
1e650 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 t*, int);.int sq
1e660 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
1e670 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1e680 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c nt, const char*,
1e690 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 int n, void(*)(
1e6a0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c void*));.int sql
1e6b0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
1e6c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1e6d0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a int, const void*
1e6e0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
1e6f0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 oid*));.int sqli
1e700 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 te3_bind_value(s
1e710 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1e720 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 t, const sqlite3
1e730 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
1e740 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
1e750 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
1e760 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a *, int, int n);.
1e770 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1e780 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 Number Of SQL P
1e790 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 arameters.**.**
1e7a0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 ^This routine ca
1e7b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e n be used to fin
1e7c0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
1e7d0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d [SQL parameters]
1e7e0 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 .** in a [prepar
1e7f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
1e800 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 SQL parameters a
1e810 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 re tokens of the
1e820 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f .** form "?", "?
1e830 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 NNN", ":AAA", "$
1e840 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 AAA", or "@AAA"
1e850 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a that serve as.**
1e860 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
1e870 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 r values that ar
1e880 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
1e890 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a blob | bound].**
1e8a0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
1e8b0 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 rs at a later ti
1e8c0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 me..**.** ^(This
1e8d0 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c routine actuall
1e8e0 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e y returns the in
1e8f0 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 dex of the large
1e900 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a st (rightmost).*
1e910 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 * parameter. For
1e920 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 all forms excep
1e930 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c t ?NNN, this wil
1e940 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 l correspond to
1e950 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
1e960 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 unique paramete
1e970 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 rs. If paramete
1e980 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 rs of the ?NNN f
1e990 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a orm are used,.**
1e9a0 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 there may be ga
1e9b0 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 ps in the list.)
1e9c0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
1e9d0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
1e9e0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
1e9f0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
1ea00 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1ea10 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a _name()], and.**
1ea20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1ea30 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
1ea40 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
1ea50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1ea60 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
1ea70 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
1ea80 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
1ea90 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 A Host Parameter
1eaa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1eab0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1eac0 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 er_name(P,N) int
1ead0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a erface returns.*
1eae0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 * the name of th
1eaf0 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 e N-th [SQL para
1eb00 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 meter] in the [p
1eb10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1eb20 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 t] P..** ^(SQL p
1eb30 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
1eb40 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 form "?NNN" or
1eb50 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 ":AAA" or "@AAA"
1eb60 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 or "$AAA".** ha
1eb70 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 ve a name which
1eb80 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f is the string "?
1eb90 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f NNN" or ":AAA" o
1eba0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 r "@AAA" or "$AA
1ebb0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 A".** respective
1ebc0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 ly..** In other
1ebd0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 words, the initi
1ebe0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 al ":" or "$" or
1ebf0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 "@" or "?".** i
1ec00 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 s included as pa
1ec10 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 rt of the name.)
1ec20 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 ^.** ^Parameters
1ec30 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 of the form "?"
1ec40 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f without a follo
1ec50 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 wing integer hav
1ec60 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 e no name.** and
1ec70 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 are also referr
1ec80 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 ed to as "namele
1ec90 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 ss" or "anonymou
1eca0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a s parameters"..*
1ecb0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
1ecc0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 host parameter h
1ecd0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
1ece0 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e , not 0..**.** ^
1ecf0 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 If the value N i
1ed00 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f s out of range o
1ed10 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 r if the N-th pa
1ed20 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 rameter is.** na
1ed30 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c meless, then NUL
1ed40 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 L is returned.
1ed50 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
1ed60 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 ring is.** alway
1ed70 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 s in UTF-8 encod
1ed80 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
1ed90 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 named parameter
1eda0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c was.** originall
1edb0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 y specified as U
1edc0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 TF-16 in [sqlite
1edd0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 3_prepare16()] o
1ede0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
1edf0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
1ee00 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
1ee10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1ee20 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
1ee30 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
1ee40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
1ee50 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b unt()], and.** [
1ee60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1ee70 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
1ee80 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
1ee90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1eea0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 ameter_name(sqli
1eeb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
1eec0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1eed0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 : Index Of A Par
1eee0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 ameter With A Gi
1eef0 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e ven Name.**.** ^
1ef00 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 Return the index
1ef10 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d of an SQL param
1ef20 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e eter given its n
1ef30 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e ame. ^The.** in
1ef40 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e dex value return
1ef50 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 ed is suitable f
1ef60 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 or use as the se
1ef70 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 cond.** paramete
1ef80 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 r to [sqlite3_bi
1ef90 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
1efa0 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 bind()]. ^A zer
1efb0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 o.** is returned
1efc0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 if no matching
1efd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 parameter is fou
1efe0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 nd. ^The parame
1eff0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 ter.** name must
1f000 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 be given in UTF
1f010 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f -8 even if the o
1f020 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e riginal statemen
1f030 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 t.** was prepare
1f040 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 d from UTF-16 te
1f050 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 xt using [sqlite
1f060 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
1f070 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
1f080 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
1f090 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
1f0a0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
1f0b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1f0c0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
1f0d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
1f0e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
1f0f0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
1f100 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1f110 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 er_index(sqlite3
1f120 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 _stmt*, const ch
1f130 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a ar *zName);../*.
1f140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
1f150 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 et All Bindings
1f160 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 On A Prepared St
1f170 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 atement.**.** ^C
1f180 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
1f190 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
1f1a0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
1f1b0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 ()] does not res
1f1c0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 et.** the [sqlit
1f1d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
1f1e0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 indings] on a [p
1f1f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1f200 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 t]..** ^Use this
1f210 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 routine to rese
1f220 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d t all host param
1f230 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a eters to NULL..*
1f240 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
1f250 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c ear_bindings(sql
1f260 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
1f270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
1f280 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 mber Of Columns
1f290 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a In A Result Set.
1f2a0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 **.** ^Return th
1f2b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
1f2c0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
1f2d0 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 t set returned b
1f2e0 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 y the.** [prepar
1f2f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e ed statement]. ^
1f300 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
1f310 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 urns 0 if pStmt
1f320 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 is an SQL.** sta
1f330 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 tement that does
1f340 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 not return data
1f350 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e (for example an
1f360 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a 69 [UPDATE])..*/.i
1f370 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
1f380 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f n_count(sqlite3_
1f390 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
1f3a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
1f3b0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 olumn Names In A
1f3c0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a Result Set.**.*
1f3d0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
1f3e0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d s return the nam
1f3f0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 e assigned to a
1f400 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d particular colum
1f410 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 n.** in the resu
1f420 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c lt set of a [SEL
1f430 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
1f440 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
1f450 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 lumn_name().** i
1f460 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
1f470 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1f480 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1f490 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
1f4a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
1f4b0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 mn_name16() retu
1f4c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1f4d0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
1f4e0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
1f4f0 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ing. ^The first
1f500 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
1f510 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
1f520 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 ement].** that i
1f530 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 mplements the [S
1f540 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
1f550 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
1f560 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
1f570 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e * column number.
1f580 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 ^The leftmost
1f590 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 column is number
1f5a0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 0..**.** ^The r
1f5b0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 eturned string p
1f5c0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 ointer is valid
1f5d0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 until either the
1f5e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1f5f0 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 ment].** is dest
1f600 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
1f610 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
1f620 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 until the next
1f630 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 call to.** sqlit
1f640 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
1f650 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
1f660 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 mn_name16() on t
1f670 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a he same column..
1f680 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 **.** ^If sqlite
1f690 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 3_malloc() fails
1f6a0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 during the proc
1f6b0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 essing of either
1f6c0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 routine.** (for
1f6d0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 example during
1f6e0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f a conversion fro
1f6f0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 m UTF-8 to UTF-1
1f700 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 6) then a.** NUL
1f710 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
1f720 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 urned..**.** ^Th
1f730 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 e name of a resu
1f740 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 lt column is the
1f750 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 value of the "A
1f760 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a S" clause for.**
1f770 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 that column, if
1f780 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 there is an AS
1f790 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 clause. If ther
1f7a0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 e is no AS claus
1f7b0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 e.** then the na
1f7c0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e me of the column
1f7d0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 is unspecified
1f7e0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 and may change f
1f7f0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 rom.** one relea
1f800 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 se of SQLite to
1f810 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e the next..*/.con
1f820 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
1f830 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c _column_name(sql
1f840 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
1f850 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a N);.const void *
1f860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
1f870 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
1f880 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a mt*, int N);../*
1f890 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f .** CAPI3REF: So
1f8a0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 urce Of Data In
1f8b0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a A Query Result.*
1f8c0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
1f8d0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d ines provide a m
1f8e0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e eans to determin
1f8f0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 e the database,
1f900 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 table, and.** ta
1f910 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
1f920 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 is the origin of
1f930 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
1f940 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a sult column in.*
1f950 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 * [SELECT] state
1f960 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 ment..** ^The na
1f970 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
1f980 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 se or table or c
1f990 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 olumn can be ret
1f9a0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 urned as.** eith
1f9b0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 er a UTF-8 or UT
1f9c0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 F-16 string. ^T
1f9d0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f he _database_ ro
1f9e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a utines return.**
1f9f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
1fa00 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 me, the _table_
1fa10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1fa20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 the table name,
1fa30 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 and.** the origi
1fa40 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 n_ routines retu
1fa50 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 rn the column na
1fa60 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 me..** ^The retu
1fa70 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 rned string is v
1fa80 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b alid until the [
1fa90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1faa0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 nt] is destroyed
1fab0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
1fac0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
1fad0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 r until the same
1fae0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
1faf0 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 requested.** aga
1fb00 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e in in a differen
1fb10 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a t encoding..**.*
1fb20 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 * ^The names ret
1fb30 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 urned are the or
1fb40 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 iginal un-aliase
1fb50 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a d names of the.*
1fb60 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c * database, tabl
1fb70 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a e, and column..*
1fb80 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
1fb90 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 argument to thes
1fba0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 e interfaces is
1fbb0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
1fbc0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 ement]..** ^Thes
1fbd0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
1fbe0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 rn information a
1fbf0 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 bout the Nth res
1fc00 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 ult column retur
1fc10 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 ned by.** the st
1fc20 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e atement, where N
1fc30 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 is the second f
1fc40 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
1fc50 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d ..** ^The left-m
1fc60 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f ost column is co
1fc70 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 lumn 0 for these
1fc80 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
1fc90 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c ^If the Nth col
1fca0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 umn returned by
1fcb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
1fcc0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f an expression o
1fcd0 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e r.** subquery an
1fce0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d d is not a colum
1fcf0 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c n value, then al
1fd00 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 l of these funct
1fd10 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e ions return.** N
1fd20 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 ULL. ^These rou
1fd30 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 tine might also
1fd40 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 return NULL if a
1fd50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1fd60 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 on error.** occu
1fd70 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c rs. ^Otherwise,
1fd80 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 they return the
1fd90 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 name of the att
1fda0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 ached database,
1fdb0 74 61 62 6c 65 0a 2a 2a 20 6f 72 20 63 6f 6c 75 table.** or colu
1fdc0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 mn that query re
1fdd0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 sult column was
1fde0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a extracted from..
1fdf0 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 **.** ^As with a
1fe00 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ll other SQLite
1fe10 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 APIs, those whos
1fe20 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 e names end with
1fe30 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 "16" return.**
1fe40 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 UTF-16 encoded s
1fe50 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f trings and the o
1fe60 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 ther functions r
1fe70 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a eturn UTF-8..**.
1fe80 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 ** ^These APIs a
1fe90 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c re only availabl
1fea0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 e if the library
1feb0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
1fec0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
1fed0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f E_ENABLE_COLUMN_
1fee0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 METADATA] C-prep
1fef0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e rocessor symbol.
1ff00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
1ff10 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
1ff20 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f ll one or more o
1ff30 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
1ff40 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d against the sam
1ff50 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 e.** prepared st
1ff60 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 atement and colu
1ff70 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 mn at the same t
1ff80 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
1ff90 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 ults are.** unde
1ffa0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 fined..**.** If
1ffb0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
1ffc0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
1ffd0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 more.** [sqlite3
1ffe0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
1fff0 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d _name | column m
20000 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 etadata interfac
20010 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 es].** for the s
20020 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 ame [prepared st
20030 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 atement] and res
20040 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 ult column.** at
20050 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
20060 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
20070 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
20080 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
20090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
200a0 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 abase_name(sqlit
200b0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
200c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
200d0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
200e0 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 se_name16(sqlite
200f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
20100 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
20110 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
20120 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
20130 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f *,int);.const vo
20140 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
20150 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 mn_table_name16(
20160 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
20170 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
20180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
20190 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 rigin_name(sqlit
201a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
201b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
201c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e e3_column_origin
201d0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
201e0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
201f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 ** CAPI3REF: Dec
20200 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f lared Datatype O
20210 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 f A Query Result
20220 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 .**.** ^(The fir
20230 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
20240 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
20250 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 ement]..** If th
20260 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 is statement is
20270 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
20280 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 ment and the Nth
20290 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a column of the.*
202a0 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c * returned resul
202b0 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 t set of that [S
202c0 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c ELECT] is a tabl
202d0 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e e column (not an
202e0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f .** expression o
202f0 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e r subquery) then
20300 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 the declared ty
20310 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a pe of the table.
20320 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 ** column is ret
20330 75 72 6e 65 64 2e 29 20 20 5e 49 66 20 74 68 65 urned.) ^If the
20340 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 Nth column of t
20350 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 he result set is
20360 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f an.** expressio
20370 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 n or subquery, t
20380 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 hen a NULL point
20390 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
203a0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 ** ^The returned
203b0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 string is alway
203c0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e s UTF-8 encoded.
203d0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 .**.** ^(For exa
203e0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 mple, given the
203f0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a database schema:
20400 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 .**.** CREATE TA
20410 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e BLE t1(c1 VARIAN
20420 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 T);.**.** and th
20430 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 e following stat
20440 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
20450 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 iled:.**.** SELE
20460 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 CT c1 + 1, c1 FR
20470 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 OM t1;.**.** thi
20480 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 s routine would
20490 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e return the strin
204a0 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 g "VARIANT" for
204b0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c the second resul
204c0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d t.** column (i==
204d0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 1), and a NULL p
204e0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 ointer for the f
204f0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 irst result colu
20500 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a mn (i==0).)^.**.
20510 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 ** ^SQLite uses
20520 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 dynamic run-time
20530 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 typing. ^So ju
20540 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c st because a col
20550 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 umn.** is declar
20560 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 ed to contain a
20570 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 particular type
20580 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 does not mean th
20590 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 at the.** data s
205a0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f tored in that co
205b0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 lumn is of the d
205c0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 eclared type. S
205d0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f QLite is.** stro
205e0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 ngly typed, but
205f0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 the typing is dy
20600 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 namic not static
20610 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 . ^Type.** is a
20620 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 ssociated with i
20630 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 ndividual values
20640 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 , not with the c
20650 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 ontainers.** use
20660 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 d to hold those
20670 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 values..*/.const
20680 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
20690 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 olumn_decltype(s
206a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
206b0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
206c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 qlite3_column_de
206d0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 cltype16(sqlite3
206e0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a _stmt*,int);../*
206f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 .** CAPI3REF: Ev
20700 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 aluate An SQL St
20710 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 atement.**.** Af
20720 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 ter a [prepared
20730 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 statement] has b
20740 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 een prepared usi
20750 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 ng either.** [sq
20760 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
20770 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
20780 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
20790 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 or one of the le
207a0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
207b0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 es [sqlite3_prep
207c0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 are()] or [sqlit
207d0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
207e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a this function.*
207f0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 * must be called
20800 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
20810 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 es to evaluate t
20820 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a he statement..**
20830 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 .** The details
20840 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 of the behavior
20850 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 of the sqlite3_s
20860 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 tep() interface
20870 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 depend.** on whe
20880 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 ther the stateme
20890 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 nt was prepared
208a0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 using the newer
208b0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a "v2" interface.*
208c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
208d0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
208e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
208f0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 v2()] or the old
20900 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 er legacy.** int
20910 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f erface [sqlite3_
20920 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
20930 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
20940 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
20950 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 f the.** new "v2
20960 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
20970 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
20980 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
20990 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
209a0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
209b0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
209c0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
209d0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 ^In the legacy
209e0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
209f0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
20a00 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
20a10 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 TE_BUSY],.** [SQ
20a20 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
20a30 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
20a40 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
20a50 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
20a60 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 ^With the "v2"
20a70 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f interface, any o
20a80 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 f the other [res
20a90 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a ult codes] or.**
20aa0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
20ab0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 t codes] might b
20ac0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 e returned as we
20ad0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ll..**.** ^[SQLI
20ae0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 TE_BUSY] means t
20af0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
20b00 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 engine was unab
20b10 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 le to acquire th
20b20 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f e.** database lo
20b30 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 cks it needs to
20b40 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 do its job. ^If
20b50 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
20b60 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 s a [COMMIT].**
20b70 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 or occurs outsid
20b80 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 e of an explicit
20b90 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 transaction, th
20ba0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 en you can retry
20bb0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
20bc0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 t. If the state
20bd0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 ment is not a [C
20be0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 OMMIT] and occur
20bf0 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 s within a.** ex
20c00 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
20c10 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 on then you shou
20c20 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 ld rollback the
20c30 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f transaction befo
20c40 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 re.** continuing
20c50 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ..**.** ^[SQLITE
20c60 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 _DONE] means tha
20c70 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
20c80 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 has finished exe
20c90 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 cuting.** succes
20ca0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 sfully. sqlite3
20cb0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e _step() should n
20cc0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 ot be called aga
20cd0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 in on this virtu
20ce0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 al.** machine wi
20cf0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c thout first call
20d00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
20d10 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 et()] to reset t
20d20 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 he virtual.** ma
20d30 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 chine back to it
20d40 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e s initial state.
20d50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 .**.** ^If the S
20d60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 QL statement bei
20d70 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 ng executed retu
20d80 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 rns any data, th
20d90 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a en [SQLITE_ROW].
20da0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 ** is returned e
20db0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 ach time a new r
20dc0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 ow of data is re
20dd0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 ady for processi
20de0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c ng by the.** cal
20df0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 ler. The values
20e00 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 may be accessed
20e10 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d using the [colum
20e20 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
20e30 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ns]..** sqlite3_
20e40 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 step() is called
20e50 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 again to retrie
20e60 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 ve the next row
20e70 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e of data..**.** ^
20e80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d [SQLITE_ERROR] m
20e90 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d eans that a run-
20ea0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 time error (such
20eb0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 as a constraint
20ec0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 .** violation) h
20ed0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 as occurred. sq
20ee0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
20ef0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
20f00 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 d again on.** th
20f10 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 e VM. More infor
20f20 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f mation may be fo
20f30 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b und by calling [
20f40 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
20f50 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 ]..** ^With the
20f60 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
20f70 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 , a more specifi
20f80 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f c error code (fo
20f90 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 r example,.** [S
20fa0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d QLITE_INTERRUPT]
20fb0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 , [SQLITE_SCHEMA
20fc0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 ], [SQLITE_CORRU
20fd0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 PT], and so fort
20fe0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 h).** can be obt
20ff0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 ained by calling
21000 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
21010 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 )] on the.** [pr
21020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
21030 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 ]. ^In the "v2"
21040 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 interface,.** t
21050 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
21060 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 error code is r
21070 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 eturned directly
21080 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
21090 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ()..**.** [SQLIT
210a0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 E_MISUSE] means
210b0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f that the this ro
210c0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 utine was called
210d0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 inappropriately
210e0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 ..** Perhaps it
210f0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 was called on a
21100 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
21110 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a ent] that has.**
21120 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 already been [s
21130 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 qlite3_finalize
21140 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 | finalized] or
21150 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a on one that had.
21160 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ** previously re
21170 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 turned [SQLITE_E
21180 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 RROR] or [SQLITE
21190 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 _DONE]. Or it c
211a0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 ould.** be the c
211b0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d ase that the sam
211c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
211d0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 ction is being u
211e0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a sed by two or.**
211f0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 more threads at
21200 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 the same moment
21210 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 in time..**.**
21220 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 <b>Goofy Interfa
21230 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e ce Alert:</b> In
21240 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
21250 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 rface, the sqlit
21260 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 e3_step().** API
21270 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
21280 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 a generic error
21290 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 code, [SQLITE_ER
212a0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 ROR], following
212b0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 any.** error oth
212c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
212d0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 BUSY] and [SQLIT
212e0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 E_MISUSE]. You
212f0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 must call.** [sq
21300 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
21310 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
21320 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 ize()] in order
21330 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 to find one of t
21340 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b he.** specific [
21350 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 error codes] tha
21360 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 t better describ
21370 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a es the error..**
21380 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 We admit that t
21390 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 his is a goofy d
213a0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 esign. The prob
213b0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 lem has been fix
213c0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 ed.** with the "
213d0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 v2" interface.
213e0 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 If you prepare a
213f0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 ll of your SQL s
21400 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 tatements.** usi
21410 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
21420 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
21430 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
21440 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 pare16_v2()] ins
21450 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c tead.** of the l
21460 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 egacy [sqlite3_p
21470 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
21480 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
21490 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a ()] interfaces,.
214a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 ** then the more
214b0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
214c0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 codes] are retu
214d0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a rned directly.**
214e0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
214f0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 (). The use of
21500 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
21510 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
21520 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
21530 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 3_step(sqlite3_s
21540 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
21550 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f PI3REF: Number o
21560 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 f columns in a r
21570 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 esult set.**.**
21580 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
21590 61 5f 63 6f 75 6e 74 28 50 29 20 74 68 65 20 6e a_count(P) the n
215a0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
215b0 20 69 6e 20 74 68 65 0a 2a 2a 20 6f 66 20 74 68 in the.** of th
215c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
215d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
215e0 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69 6e 74 20 73 ent] P..*/.int s
215f0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
21600 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
21610 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
21620 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 API3REF: Fundame
21630 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a ntal Datatypes.*
21640 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 * KEYWORDS: SQLI
21650 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 TE_TEXT.**.** ^(
21660 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 Every value in S
21670 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 QLite has one of
21680 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 five fundamenta
21690 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a l datatypes:.**.
216a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
216b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
216c0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 teger.** <li> 64
216d0 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 -bit IEEE floati
216e0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a ng point number.
216f0 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a ** <li> string.*
21700 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c * <li> BLOB.** <
21710 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c li> NULL.** </ul
21720 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 >)^.**.** These
21730 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f constants are co
21740 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 des for each of
21750 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a those types..**.
21760 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
21770 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e SQLITE_TEXT con
21780 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 stant was also u
21790 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 sed in SQLite ve
217a0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 rsion 2.** for a
217b0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 completely diff
217c0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 erent meaning.
217d0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 Software that li
217e0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 nks against both
217f0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 .** SQLite versi
21800 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 on 2 and SQLite
21810 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 version 3 should
21820 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 use SQLITE3_TEX
21830 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 T, not.** SQLITE
21840 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e _TEXT..*/.#defin
21850 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 e SQLITE_INTEGER
21860 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
21870 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 TE_FLOAT 2.#d
21880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f efine SQLITE_BLO
21890 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 B 4.#define
218a0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 SQLITE_NULL
218b0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 5.#ifdef SQLITE_
218c0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c TEXT.# undef SQL
218d0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 ITE_TEXT.#else.#
218e0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 define SQLITE_T
218f0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 EXT 3.#endif
21900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 .#define SQLITE3
21910 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a _TEXT 3../*.
21920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
21930 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 ult Values From
21940 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f A Query.** KEYWO
21950 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 RDS: {column acc
21960 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a ess functions}.*
21970 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
21980 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 nes form the "re
21990 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 sult set" interf
219a0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ace..**.** ^Thes
219b0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
219c0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 n information ab
219d0 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c out a single col
219e0 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 umn of the curre
219f0 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 nt.** result row
21a00 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 of a query. ^I
21a10 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 n every case the
21a20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
21a30 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 is a pointer.**
21a40 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 to the [prepared
21a50 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
21a60 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 is being evalua
21a70 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 ted (the [sqlite
21a80 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 3_stmt*].** that
21a90 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 was returned fr
21aa0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 om [sqlite3_prep
21ab0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 are_v2()] or one
21ac0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 of its variants
21ad0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 ).** and the sec
21ae0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
21af0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
21b00 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 column for whic
21b10 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a h information.**
21b20 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 should be retur
21b30 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f ned. ^The leftmo
21b40 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 st column of the
21b50 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 result set has
21b60 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 the index 0..**
21b70 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 ^The number of c
21b80 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
21b90 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 sult can be dete
21ba0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 rmined using.**
21bb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
21bc0 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 count()]..**.**
21bd0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
21be0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 ment does not cu
21bf0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f rrently point to
21c00 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 a valid row, or
21c10 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d if the.** colum
21c20 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f n index is out o
21c30 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 f range, the res
21c40 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ult is undefined
21c50 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
21c60 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 nes may only be
21c70 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 called when the
21c80 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
21c90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
21ca0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 step()] has retu
21cb0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 rned [SQLITE_ROW
21cc0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a ] and neither.**
21cd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
21ce0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f )] nor [sqlite3_
21cf0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 finalize()] have
21d00 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 been called sub
21d10 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 sequently..** If
21d20 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
21d30 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
21d40 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 d after [sqlite3
21d50 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
21d60 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
21d70 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 e()] or after [s
21d80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
21d90 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 as returned.** s
21da0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 omething other t
21db0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
21dc0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 , the results ar
21dd0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 e undefined..**
21de0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 If [sqlite3_step
21df0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
21e00 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c reset()] or [sql
21e10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
21e20 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 .** are called f
21e30 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 rom a different
21e40 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 thread while any
21e50 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
21e60 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e es.** are pendin
21e70 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 g, then the resu
21e80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
21e90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
21ea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
21eb0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
21ec0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 rns the.** [SQLI
21ed0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
21ee0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 atype code] for
21ef0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 the initial data
21f00 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 type.** of the
21f10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 result column.
21f20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 ^The returned va
21f30 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 lue is one of [S
21f40 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a QLITE_INTEGER],.
21f50 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 ** [SQLITE_FLOAT
21f60 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d ], [SQLITE_TEXT]
21f70 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c , [SQLITE_BLOB],
21f80 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c or [SQLITE_NULL
21f90 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a ]. The value.**
21fa0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
21fb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
21fc0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 () is only meani
21fd0 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 ngful if no type
21fe0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 .** conversions
21ff0 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 have occurred as
22000 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 described below
22010 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 . After a type
22020 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 conversion,.** t
22030 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
22040 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
22050 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e umn_type() is un
22060 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 defined. Future
22070 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 .** versions of
22080 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 SQLite may chang
22090 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f e the behavior o
220a0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e f sqlite3_column
220b0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f _type().** follo
220c0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 wing a type conv
220d0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ersion..**.** ^I
220e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
220f0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 a BLOB or UTF-8
22100 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 string then the
22110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
22120 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e ytes().** routin
22130 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
22140 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
22150 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 that BLOB or st
22160 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
22170 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 result is a UTF
22180 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e -16 string, then
22190 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
221a0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 bytes() converts
221b0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 .** the string t
221c0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e o UTF-8 and then
221d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
221e0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a ber of bytes..**
221f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
22200 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c is a numeric val
22210 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ue then sqlite3_
22220 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 column_bytes() u
22230 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ses.** [sqlite3_
22240 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 snprintf()] to c
22250 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 onvert that valu
22260 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 e to a UTF-8 str
22270 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
22280 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
22290 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
222a0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54 68 65 20 76 tring..** ^The v
222b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f alue returned do
222c0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 es not include t
222d0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
222e0 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a or at the end.**
222f0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 of the string.
22300 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 ^For clarity: t
22310 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
22320 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 d is the number
22330 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 of.** bytes in t
22340 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 he string, not t
22350 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
22360 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e racters..**.** ^
22370 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 Strings returned
22380 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
22390 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 mn_text() and sq
223a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
223b0 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 t16(),.** even e
223c0 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 mpty strings, ar
223d0 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 e always zero te
223e0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 rminated. ^The
223f0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
22400 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c from sqlite3_col
22410 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 umn_blob() for a
22420 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
22430 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 B is an arbitrar
22440 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f y.** pointer, po
22450 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 ssibly even a NU
22460 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
22470 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
22480 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
22490 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c routine is simil
224a0 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ar to sqlite3_co
224b0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 lumn_bytes().**
224c0 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 but leaves the r
224d0 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 esult in UTF-16
224e0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
224f0 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 rder instead of
22500 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54 68 65 20 7a UTF-8..** ^The z
22510 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 ero terminator i
22520 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 s not included i
22530 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a n this count..**
22540 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 .** ^The object
22550 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
22560 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
22570 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 e()] is an.** [u
22580 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
22590 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
225a0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 . An unprotecte
225b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
225c0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e object.** may on
225d0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ly be used with
225e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
225f0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 lue()] and [sqli
22600 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
22610 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b ()]..** If the [
22620 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
22630 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
22640 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
22650 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
22660 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 _value()] is use
22670 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 d in any other w
22680 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 ay, including ca
22690 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e lls.** to routin
226a0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 es like [sqlite3
226b0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b _value_int()], [
226c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
226d0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
226e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
226f0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 s()], then the b
22700 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
22710 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ined..**.** Thes
22720 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d e routines attem
22730 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 pt to convert th
22740 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 e value where ap
22750 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 propriate. ^For
22760 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 .** example, if
22770 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 the internal rep
22780 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 resentation is F
22790 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 LOAT and a text
227a0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 result.** is req
227b0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 uested, [sqlite3
227c0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 _snprintf()] is
227d0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 used internally
227e0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a to perform the.*
227f0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 * conversion aut
22800 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 omatically. ^(T
22810 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 he following tab
22820 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 le details the c
22830 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 onversions.** th
22840 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a at are applied:.
22850 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
22860 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 e>.** <table bor
22870 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e der="1">.** <tr>
22880 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 <th> Internal<br
22890 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 >Type <th> Reque
228a0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 sted<br>Type <th
228b0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a > Conversion.**
228c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
228d0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 LL <td> INTEG
228e0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 ER <td> Result
228f0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 is 0.** <tr><td
22900 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
22910 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 FLOAT <td> R
22920 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 esult is 0.0.**
22930 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
22940 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
22950 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
22960 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
22970 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
22980 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
22990 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
229a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
229b0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
229c0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
229d0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
229e0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c om integer to fl
229f0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
22a00 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
22a10 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
22a20 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
22a30 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c the integer.** <
22a40 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
22a50 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
22a60 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 <td> Same as INT
22a70 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 EGER->TEXT.** <t
22a80 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
22a90 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
22aa0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
22ab0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 float to intege
22ac0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 r.** <tr><td> F
22ad0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 LOAT <td> TE
22ae0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
22af0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
22b00 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c e float.** <tr><
22b10 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
22b20 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
22b30 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e Same as FLOAT->
22b40 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e TEXT.** <tr><td>
22b50 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 TEXT <td> I
22b60 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 NTEGER <td> Us
22b70 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e e atoi().** <tr>
22b80 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
22b90 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
22ba0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 > Use atof().**
22bb0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
22bc0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
22bd0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a <td> No change.
22be0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
22bf0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 B <td> INTEGE
22c00 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 R <td> Convert
22c10 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 to TEXT then us
22c20 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e e atoi().** <tr>
22c30 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
22c40 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
22c50 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 > Convert to TEX
22c60 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 T then use atof(
22c70 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 ).** <tr><td> B
22c80 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 LOB <td> TE
22c90 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 XT <td> Add a
22ca0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
22cb0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f if needed.** </
22cc0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 table>.** </bloc
22cd0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
22ce0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 The table above
22cf0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 makes reference
22d00 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 to standard C li
22d10 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 brary functions
22d20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 atoi().** and at
22d30 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f of(). SQLite do
22d40 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 es not really us
22d50 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e e these function
22d60 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a s. It has its.*
22d70 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 * own equivalent
22d80 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e internal routin
22d90 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 es. The atoi()
22da0 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 and atof() names
22db0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 are.** used in
22dc0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 the table for br
22dd0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 evity and becaus
22de0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c e they are famil
22df0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 iar to most.** C
22e00 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a programmers..**
22e10 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 77 .** ^Note that w
22e20 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 hen type convers
22e30 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e ions occur, poin
22e40 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 ters returned by
22e50 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 prior.** calls
22e60 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
22e70 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 n_blob(), sqlite
22e80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
22e90 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 and/or.** sqlit
22ea0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
22eb0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 () may be invali
22ec0 64 61 74 65 64 2e 0a 2a 2a 20 5e 28 54 79 70 65 dated..** ^(Type
22ed0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 conversions and
22ee0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 pointer invalid
22ef0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 ations might occ
22f00 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c ur.** in the fol
22f10 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a lowing cases:.**
22f20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
22f30 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
22f40 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 tent is a BLOB a
22f50 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
22f60 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 n_text() or.**
22f70 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
22f80 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 mn_text16() is c
22f90 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 alled. A zero-t
22fa0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a erminator might.
22fb0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 ** need to
22fc0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 be added to the
22fd0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 string.</li>.**
22fe0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
22ff0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d content is UTF-
23000 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 8 text and sqlit
23010 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
23020 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 6() or.** s
23030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
23040 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 xt16() is called
23050 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d . The content m
23060 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
23070 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d .** to UTF-
23080 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 16.</li>.** <li>
23090 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
230a0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 tent is UTF-16 t
230b0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
230c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f column_bytes() o
230d0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
230e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
230f0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
23100 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 content must be
23110 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 converted.**
23120 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e to UTF-8.</li>
23130 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a .** </ul>)^.**.*
23140 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 * ^Conversions b
23150 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 etween UTF-16be
23160 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 and UTF-16le are
23170 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 always done in
23180 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 place and do.**
23190 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 not invalidate a
231a0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 prior pointer,
231b0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 though of course
231c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
231d0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 the buffer.** th
231e0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 at the prior poi
231f0 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 nter points to w
23200 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f ill have been mo
23210 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b dified. Other k
23220 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 inds.** of conve
23230 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 rsion are done i
23240 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 n place when it
23250 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 is possible, but
23260 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a sometimes they.
23270 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 ** are not possi
23280 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 ble and in those
23290 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 cases prior poi
232a0 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 nters are invali
232b0 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 dated..**.** ^(T
232c0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 he safest and ea
232d0 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 siest to remembe
232e0 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 r policy is to i
232f0 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 nvoke these rout
23300 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f ines.** in one o
23310 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
23320 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ways:.**.** <ul>
23330 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
23340 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 _column_text() f
23350 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
23360 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
23370 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
23380 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
23390 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 ob() followed by
233a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
233b0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
233c0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
233d0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c umn_text16() fol
233e0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
233f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
23400 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 )</li>.** </ul>)
23410 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 ^.**.** In other
23420 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 words, you shou
23430 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f ld call sqlite3_
23440 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a column_text(),.*
23450 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
23460 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 _blob(), or sqli
23470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
23480 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 6() first to for
23490 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a ce the result.**
234a0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 into the desire
234b0 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 d format, then i
234c0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f nvoke sqlite3_co
234d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a lumn_bytes() or.
234e0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
234f0 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 n_bytes16() to f
23500 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ind the size of
23510 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 the result. Do
23520 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a not mix calls.**
23530 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
23540 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c mn_text() or sql
23550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
23560 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f () with calls to
23570 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
23580 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e mn_bytes16(), an
23590 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c d do not mix cal
235a0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
235b0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a lumn_text16().**
235c0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 with calls to s
235d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
235e0 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tes()..**.** ^Th
235f0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
23600 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e ned are valid un
23610 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 til a type conve
23620 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a rsion occurs as.
23630 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f ** described abo
23640 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 ve, or until [sq
23650 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
23660 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
23670 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
23680 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 3_finalize()] is
23690 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d called. ^The m
236a0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 emory space used
236b0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 to hold strings
236c0 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 .** and BLOBs is
236d0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 freed automatic
236e0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 ally. Do <b>not
236f0 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f </b> pass the po
23700 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a inters returned.
23710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
23720 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c mn_blob()], [sql
23730 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
23740 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a ()], etc. into.*
23750 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
23760 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 )]..**.** ^(If a
23770 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
23780 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 on error occurs
23790 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 during the evalu
237a0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 ation of any.**
237b0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
237c0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c s, a default val
237d0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 ue is returned.
237e0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c The default val
237f0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 ue.** is either
23800 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 the integer 0, t
23810 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e he floating poin
23820 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 t number 0.0, or
23830 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
23840 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 er. Subsequent
23850 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
23860 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 3_errcode()] wil
23870 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c l return.** [SQL
23880 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f ITE_NOMEM].)^.*/
23890 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
238a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
238b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
238c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 int iCol);.int s
238d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
238e0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tes(sqlite3_stmt
238f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e *, int iCol);.in
23900 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
23910 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 _bytes16(sqlite3
23920 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
23930 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 );.double sqlite
23940 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 3_column_double(
23950 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
23960 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
23970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
23980 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
23990 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 int iCol);.sqlit
239a0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
239b0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 _column_int64(sq
239c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
239d0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e iCol);.const un
239e0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c signed char *sql
239f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
23a00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
23a10 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 int iCol);.const
23a20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
23a30 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c olumn_text16(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 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
23a60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 e3_column_type(s
23a70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
23a80 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 t iCol);.sqlite3
23a90 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f _value *sqlite3_
23aa0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c column_value(sql
23ab0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
23ac0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 iCol);../*.** CA
23ad0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 PI3REF: Destroy
23ae0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
23af0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a ment Object.**.*
23b00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 * ^The sqlite3_f
23b10 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 inalize() functi
23b20 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 on is called to
23b30 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 delete a [prepar
23b40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
23b50 2a 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d * ^If the statem
23b60 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64 ent was executed
23b70 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 successfully or
23b80 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 not executed at
23b90 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 all, then.** SQ
23ba0 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 LITE_OK is retur
23bb0 6e 65 64 2e 20 5e 49 66 20 65 78 65 63 75 74 69 ned. ^If executi
23bc0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d on of the statem
23bd0 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 ent failed then
23be0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 an.** [error cod
23bf0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 e] or [extended
23c00 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
23c10 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
23c20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e This routine can
23c30 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e be called at an
23c40 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 y point during t
23c50 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 he execution of
23c60 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
23c70 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 statement]. ^I
23c80 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 f the virtual ma
23c90 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a chine has not.**
23ca0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 completed execu
23cb0 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 tion when this r
23cc0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 outine is called
23cd0 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a , that is like.*
23ce0 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 * encountering a
23cf0 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 n error or an [s
23d00 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
23d10 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a | interrupt]..*
23d20 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 * ^Incomplete up
23d30 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c dates may be rol
23d40 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 led back and tra
23d50 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c nsactions cancel
23d60 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 ed,.** depending
23d70 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 on the circumst
23d80 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a ances, and the.*
23d90 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 * [error code] r
23da0 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 eturned will be
23db0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a [SQLITE_ABORT]..
23dc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 */.int sqlite3_f
23dd0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f inalize(sqlite3_
23de0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
23df0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
23e00 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 eset A Prepared
23e10 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
23e20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
23e30 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 e3_reset() funct
23e40 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
23e50 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 reset a [prepar
23e60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
23e70 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 object back to
23e80 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 its initial stat
23e90 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 e, ready to be r
23ea0 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e e-executed..** ^
23eb0 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e Any SQL statemen
23ec0 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 t variables that
23ed0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e had values boun
23ee0 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a d to them using.
23ef0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
23f00 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 bind_blob | sqli
23f10 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 te3_bind_*() API
23f20 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 ] retain their v
23f30 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 alues..** Use [s
23f40 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e qlite3_clear_bin
23f50 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 dings()] to rese
23f60 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a t the bindings..
23f70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
23f80 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e te3_reset(S)] in
23f90 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 terface resets t
23fa0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
23fb0 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 tement] S.** bac
23fc0 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 k to the beginni
23fd0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 ng of its progra
23fe0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 m..**.** ^If the
23ff0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
24000 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
24010 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a ep(S)] for the.*
24020 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
24030 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 ement] S returne
24040 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f d [SQLITE_ROW] o
24050 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c r [SQLITE_DONE],
24060 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 .** or if [sqlit
24070 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 e3_step(S)] has
24080 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 never before bee
24090 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a n called on S,.*
240a0 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f * then [sqlite3_
240b0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e reset(S)] return
240c0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a s [SQLITE_OK]..*
240d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 *.** ^If the mos
240e0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
240f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
24100 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 )] for the.** [p
24110 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
24120 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 t] S indicated a
24130 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a n error, then.**
24140 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
24150 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 S)] returns an a
24160 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
24170 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e r code]..**.** ^
24180 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
24190 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 et(S)] interface
241a0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 does not change
241b0 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f the values.** o
241c0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 f any [sqlite3_b
241d0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 ind_blob|binding
241e0 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 s] on the [prepa
241f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
24200 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
24210 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 _reset(sqlite3_s
24220 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
24230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 .** CAPI3REF: Cr
24240 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 eate Or Redefine
24250 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a SQL Functions.*
24260 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e * KEYWORDS: {fun
24270 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 ction creation r
24280 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 outines}.** KEYW
24290 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
242a0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
242b0 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 unction}.** KEYW
242c0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
242d0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
242e0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 unctions}.**.**
242f0 5e 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 ^These two funct
24300 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 ions (collective
24310 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e ly known as "fun
24320 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 ction creation r
24330 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 outines").** are
24340 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c used to add SQL
24350 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
24360 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 gregates or to r
24370 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 edefine the beha
24380 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 vior.** of exist
24390 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ing SQL function
243a0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e s or aggregates.
243b0 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 The only diffe
243c0 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 rence between th
243d0 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74 e.** two is that
243e0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
243f0 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 meter, the name
24400 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 of the (scalar)
24410 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
24420 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 ggregate, is enc
24430 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f oded in UTF-8 fo
24440 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
24450 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 _function() and
24460 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 UTF-16.** for sq
24470 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
24480 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a ction16()..**.**
24490 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
244a0 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 eter is the [dat
244b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
244c0 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 ] to which the S
244d0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 QL.** function i
244e0 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 s to be added.
244f0 5e 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f ^If a single pro
24500 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 gram uses more t
24510 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 han one database
24520 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 .** connection i
24530 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 nternally, then
24540 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 SQL functions mu
24550 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 st be added indi
24560 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 vidually to.** e
24570 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
24580 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 nection..**.** T
24590 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
245a0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ter is the name
245b0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 of the SQL funct
245c0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 ion to be create
245d0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 d or.** redefine
245e0 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 d. ^The length
245f0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c of the name is l
24600 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 imited to 255 by
24610 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f tes, exclusive o
24620 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 f.** the zero-te
24630 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 rminator. Note
24640 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 that the name le
24650 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e ngth limit is in
24660 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 bytes, not.** c
24670 68 61 72 61 63 74 65 72 73 2e 20 20 5e 41 6e 79 haracters. ^Any
24680 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 attempt to crea
24690 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 te a function wi
246a0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 th a longer name
246b0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 .** will result
246c0 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 in [SQLITE_ERROR
246d0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 ] being returned
246e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 ..**.** ^The thi
246f0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 rd parameter (nA
24700 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 rg).** is the nu
24710 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
24720 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 s that the SQL f
24730 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
24740 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e gregate takes. ^
24750 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 If this paramete
24760 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 r is -1, then th
24770 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
24780 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d r.** aggregate m
24790 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 ay take any numb
247a0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
247b0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 between 0 and th
247c0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 e limit.** set b
247d0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 y [sqlite3_limit
247e0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ]([SQLITE_LIMIT_
247f0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 FUNCTION_ARG]).
24800 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a If the third.**
24810 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 parameter is le
24820 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 ss than -1 or gr
24830 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 eater than 127 t
24840 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
24850 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 is.** undefined
24860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 ..**.** The four
24870 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 th parameter, eT
24880 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 extRep, specifie
24890 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 s what.** [SQLIT
248a0 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e E_UTF8 | text en
248b0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c coding] this SQL
248c0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 function prefer
248d0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 s for.** its par
248e0 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 ameters. Any SQ
248f0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 L function imple
24900 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 mentation should
24910 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b be able to work
24920 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 .** work with UT
24930 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f F-8, UTF-16le, o
24940 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 r UTF-16be. But
24950 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 some implementa
24960 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 tions may be.**
24970 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 more efficient w
24980 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 ith one encoding
24990 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 than another.
249a0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ^An application
249b0 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 may.** invoke sq
249c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
249d0 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 ction() or sqlit
249e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
249f0 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a on16() multiple.
24a00 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 ** times with th
24a10 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
24a20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 but with differe
24a30 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 nt values of eTe
24a40 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 xtRep..** ^When
24a50 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
24a60 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
24a70 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 same function ar
24a80 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c e available, SQL
24a90 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b ite.** will pick
24aa0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e the one that in
24ab0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 volves the least
24ac0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 amount of data
24ad0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 conversion..** I
24ae0 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 f there is only
24af0 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 a single impleme
24b00 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f ntation which do
24b10 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 es not care what
24b20 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e text.** encodin
24b30 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 g is used, then
24b40 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
24b50 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 ent should be [S
24b60 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a QLITE_ANY]..**.*
24b70 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 * ^(The fifth pa
24b80 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 rameter is an ar
24b90 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e bitrary pointer.
24ba0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 The implementa
24bb0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 tion of the.** f
24bc0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e unction can gain
24bd0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 access to this
24be0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 pointer using [s
24bf0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
24c00 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ()].)^.**.** The
24c10 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 seventh, eighth
24c20 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d and ninth param
24c30 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 eters, xFunc, xS
24c40 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 tep and xFinal,
24c50 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 are.** pointers
24c60 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 to C-language fu
24c70 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 nctions that imp
24c80 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
24c90 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
24ca0 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c gregate. ^A scal
24cb0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ar SQL function
24cc0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
24cd0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
24ce0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 e xFunc.** callb
24cf0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 ack only; NULL p
24d00 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 ointers should b
24d10 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
24d20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
24d30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 .** parameters.
24d40 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 ^An aggregate SQ
24d50 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
24d60 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
24d70 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a ation of xStep.*
24d80 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 * and xFinal and
24d90 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 NULL should be
24da0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 passed for xFunc
24db0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 . ^To delete an
24dc0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 existing.** SQL
24dd0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 function or aggr
24de0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c egate, pass NULL
24df0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 for all three f
24e00 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b unction callback
24e10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 s..**.** ^It is
24e20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 permitted to reg
24e30 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 ister multiple i
24e40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
24e50 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 f the same.** fu
24e60 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 nctions with the
24e70 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 same name but w
24e80 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 ith either diffe
24e90 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a ring numbers of.
24ea0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 ** arguments or
24eb0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 differing prefer
24ec0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
24ed0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c gs. ^SQLite wil
24ee0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 l use.** the imp
24ef0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 lementation that
24f00 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 most closely ma
24f10 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e tches the way in
24f20 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 which the.** SQ
24f30 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 L function is us
24f40 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e ed. ^A function
24f50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
24f60 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 with a non-negat
24f70 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 ive.** nArg para
24f80 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 meter is a bette
24f90 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 r match than a f
24fa0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
24fb0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 tation with.** a
24fc0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 negative nArg.
24fd0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 ^A function whe
24fe0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 re the preferred
24ff0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a text encoding.*
25000 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 * matches the da
25010 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 tabase encoding
25020 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d is a better.** m
25030 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 atch than a func
25040 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 tion where the e
25050 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 ncoding is diffe
25060 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 rent. .** ^A fu
25070 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
25080 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 encoding differ
25090 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 ence is between
250a0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 UTF16le and UTF1
250b0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 6be.** is a clos
250c0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 er match than a
250d0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
250e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 he encoding diff
250f0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 erence is.** bet
25100 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 ween UTF8 and UT
25110 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c F16..**.** ^Buil
25120 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d t-in functions m
25130 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 ay be overloaded
25140 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 by new applicat
25150 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
25160 74 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 tions..** ^The f
25170 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e irst application
25180 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
25190 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e n with a given n
251a0 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c ame overrides al
251b0 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 l.** built-in fu
251c0 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 nctions in the s
251d0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
251e0 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 nnection] with t
251f0 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a he same name..**
25200 20 5e 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 ^Subsequent app
25210 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
25220 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 functions of th
25230 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 e same name only
25240 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 override .** pr
25250 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d ior application-
25260 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
25270 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 s that are an ex
25280 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 act match for th
25290 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 e.** number of p
252a0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 arameters and pr
252b0 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 eferred encoding
252c0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c ..**.** ^An appl
252d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
252e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d function is perm
252f0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 itted to call ot
25300 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
25310 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 terfaces. Howev
25320 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d er, such calls m
25330 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 ust not.** close
25340 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
25350 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e nnection nor fin
25360 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 alize or reset t
25370 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 he prepared.** s
25380 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 tatement in whic
25390 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 h the function i
253a0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e s running..*/.in
253b0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
253c0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c _function(. sql
253d0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
253e0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
253f0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
25400 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
25410 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
25420 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
25430 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
25440 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
25450 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
25460 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
25470 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
25480 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
25490 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
254a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
254b0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
254c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
254d0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
254e0 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 b,. const void
254f0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
25500 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
25510 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
25520 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
25530 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
25540 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
25550 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
25560 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
25570 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
25580 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
25590 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
255a0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
255b0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f _context*).);../
255c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
255d0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a ext Encodings.**
255e0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
255f0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 nt define intege
25600 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 r codes that rep
25610 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f resent the vario
25620 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 us.** text encod
25630 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 ings supported b
25640 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 y SQLite..*/.#de
25650 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 fine SQLITE_UTF8
25660 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 1.#de
25670 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
25680 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 6LE 2.#de
25690 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
256a0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 6BE 3.#de
256b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
256c0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 6 4
256d0 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 /* Use native by
256e0 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 te order */.#def
256f0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 ine SQLITE_ANY
25700 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 5 /
25710 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
25720 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a _function only *
25730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
25740 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 _UTF16_ALIGNED
25750 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 8 /* sqlite3_
25760 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
25770 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 only */../*.**
25780 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 CAPI3REF: Deprec
25790 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ated Functions.*
257a0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a * DEPRECATED.**.
257b0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
257c0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 ns are [deprecat
257d0 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 ed]. In order t
257e0 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 o maintain.** ba
257f0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
25800 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 ility with older
25810 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e code, these fun
25820 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 ctions continue
25830 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 .** to be suppor
25840 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e ted. However, n
25850 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
25860 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 should avoid.**
25870 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 the use of these
25880 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 functions. To
25890 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 help encourage p
258a0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a eople to avoid.*
258b0 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 * using these fu
258c0 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 nctions, we are
258d0 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c not going to tel
258e0 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 l you what they
258f0 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 do..*/.#ifndef S
25900 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 QLITE_OMIT_DEPRE
25910 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 CATED.SQLITE_DEP
25920 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
25930 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
25940 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 unt(sqlite3_cont
25950 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 ext*);.SQLITE_DE
25960 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
25970 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c ite3_expired(sql
25980 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c ite3_stmt*);.SQL
25990 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
259a0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 nt sqlite3_trans
259b0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c fer_bindings(sql
259c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 ite3_stmt*, sqli
259d0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
259e0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
259f0 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c t sqlite3_global
25a00 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a _recover(void);.
25a10 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
25a20 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 D void sqlite3_t
25a30 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f hread_cleanup(vo
25a40 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 id);.SQLITE_DEPR
25a50 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
25a60 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 e3_memory_alarm(
25a70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
25a80 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 lite3_int64,int)
25a90 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 ,void*,sqlite3_i
25aa0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt64);.#endif../
25ab0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
25ac0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e btaining SQL Fun
25ad0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 ction Parameter
25ae0 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Values.**.** The
25af0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c C-language impl
25b00 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 ementation of SQ
25b10 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
25b20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a aggregates uses.
25b30 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 ** this set of i
25b40 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 nterface routine
25b50 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
25b60 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 parameter values
25b70 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 on.** the funct
25b80 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
25b90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e ..**.** The xFun
25ba0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 c (for scalar fu
25bb0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 nctions) or xSte
25bc0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 p (for aggregate
25bd0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a s) parameters.**
25be0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
25bf0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
25c00 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
25c10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
25c20 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c ].** define call
25c30 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 backs that imple
25c40 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
25c50 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
25c60 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 gates..** The 4t
25c70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
25c80 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 hese callbacks i
25c90 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
25ca0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 inters to.** [pr
25cb0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
25cc0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 value] objects.
25cd0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 There is one [s
25ce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
25cf0 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 ject for.** each
25d00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
25d10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 e SQL function.
25d20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
25d30 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 are used to.** e
25d40 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 xtract values fr
25d50 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
25d60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
25d70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
25d80 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 ines work only w
25d90 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 ith [protected s
25da0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
25db0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 jects..** Any at
25dc0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
25dd0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 se routines on a
25de0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 n [unprotected s
25df0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
25e00 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 object results
25e10 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
25e20 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 avior..**.** ^Th
25e30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 ese routines wor
25e40 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 k just like the
25e50 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 corresponding [c
25e60 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e olumn access fun
25e70 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 ctions].** excep
25e80 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f t that these ro
25e90 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 utines take a si
25ea0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 ngle [protected
25eb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
25ec0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 bject.** pointer
25ed0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 instead of a [s
25ee0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f qlite3_stmt*] po
25ef0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 inter and an int
25f00 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 eger column numb
25f10 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
25f20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
25f30 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 t16() interface
25f40 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 extracts a UTF-1
25f50 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 6 string.** in t
25f60 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f he native byte-o
25f70 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 rder of the host
25f80 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a machine. ^The.
25f90 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
25fa0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 _text16be() and
25fb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
25fc0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 xt16le() interfa
25fd0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 ces.** extract U
25fe0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 TF-16 strings as
25ff0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 big-endian and
26000 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 little-endian re
26010 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a spectively..**.*
26020 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f * ^(The sqlite3_
26030 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 value_numeric_ty
26040 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 pe() interface a
26050 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 ttempts to apply
26060 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 .** numeric affi
26070 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 nity to the valu
26080 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 e. This means t
26090 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 hat an attempt i
260a0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e s.** made to con
260b0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 vert the value t
260c0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 o an integer or
260d0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 floating point.
260e0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f If.** such a co
260f0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 nversion is poss
26100 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 ible without los
26110 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e s of information
26120 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f (in other.** wo
26130 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 rds, if the valu
26140 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 e is a string th
26150 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 at looks like a
26160 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 number).** then
26170 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 the conversion i
26180 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 s performed. Ot
26190 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 herwise no conve
261a0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a rsion occurs..**
261b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 The [SQLITE_INT
261c0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d EGER | datatype]
261d0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f after conversio
261e0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e n is returned.)^
261f0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 .**.** Please pa
26200 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 y particular att
26210 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 ention to the fa
26220 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e ct that the poin
26230 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 ter returned.**
26240 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 from [sqlite3_va
26250 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 lue_blob()], [sq
26260 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
26270 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
26280 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
26290 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c ()] can be inval
262a0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 idated by a subs
262b0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a equent call to.*
262c0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
262d0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 _bytes()], [sqli
262e0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 te3_value_bytes1
262f0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 6()], [sqlite3_v
26300 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a alue_text()],.**
26310 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c or [sqlite3_val
26320 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a ue_text16()]..**
26330 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
26340 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 es must be calle
26350 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
26360 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 thread as.** the
26370 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 SQL function th
26380 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 at supplied the
26390 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d [sqlite3_value*]
263a0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a parameters..*/.
263b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
263c0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 te3_value_blob(s
263d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
263e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
263f0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f e_bytes(sqlite3_
26400 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
26410 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
26420 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
26430 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 *);.double sqlit
26440 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 e3_value_double(
26450 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
26460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
26470 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 ue_int(sqlite3_v
26480 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f alue*);.sqlite3_
26490 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 int64 sqlite3_va
264a0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 lue_int64(sqlite
264b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
264c0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
264d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
264e0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 xt(sqlite3_value
264f0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a *);.const void *
26500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
26510 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c xt16(sqlite3_val
26520 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 ue*);.const void
26530 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
26540 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 text16le(sqlite3
26550 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
26560 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
26570 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c lue_text16be(sql
26580 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
26590 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
265a0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c type(sqlite3_val
265b0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
265c0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 3_value_numeric_
265d0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c type(sqlite3_val
265e0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ue*);../*.** CAP
265f0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 I3REF: Obtain Ag
26600 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e gregate Function
26610 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 Context.**.** I
26620 6d 70 6c 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 mplementions of
26630 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
26640 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 nctions use this
26650 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 .** routine to a
26660 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 llocate memory f
26670 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 or storing their
26680 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 state..**.** ^T
26690 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 he first time th
266a0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 e sqlite3_aggreg
266b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
266c0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c routine is call
266d0 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 ed .** for a par
266e0 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 ticular aggregat
266f0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 e function, SQLi
26700 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 te.** allocates
26710 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 N of memory, zer
26720 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d oes out that mem
26730 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 ory, and returns
26740 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
26750 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e the new memory.
26760 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 ^On second and
26770 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
26780 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 to.** sqlite3_a
26790 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
267a0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 () for the same
267b0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
267c0 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 on instance,.**
267d0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 the same buffer
267e0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 is returned. Sq
267f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
26800 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 context() is nor
26810 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 mally.** called
26820 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e once for each in
26830 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 vocation of the
26840 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 xStep callback a
26850 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c nd then one.** l
26860 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 ast time when th
26870 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 e xFinal callbac
26880 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e k is invoked. ^
26890 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 (When no rows ma
268a0 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 tch.** an aggreg
268b0 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 ate query, the x
268c0 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 Step() callback
268d0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 of the aggregate
268e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 function.** imp
268f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e lementation is n
26900 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 ever called and
26910 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c xFinal() is call
26920 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e ed exactly once.
26930 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 .** In those cas
26940 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 es, sqlite3_aggr
26950 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
26960 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 might be called
26970 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 for the.** first
26980 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 time from withi
26990 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a n xFinal().)^.**
269a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
269b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
269c0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 xt(C,N) routine
269d0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
269e0 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a ointer if N is.*
269f0 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 * less than or e
26a00 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 qual to zero or
26a10 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f if a memory allo
26a20 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 cate error occur
26a30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 s..**.** ^(The a
26a40 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 mount of space a
26a50 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 llocated by sqli
26a60 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
26a70 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a ntext(C,N) is.**
26a80 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 determined by t
26a90 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f he N parameter o
26aa0 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 n first successf
26ab0 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 ul call. Changi
26ac0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 ng the.** value
26ad0 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 of N in subseque
26ae0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 nt call to sqlit
26af0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
26b00 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a text() within.**
26b10 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 the same aggreg
26b20 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 ate function ins
26b30 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 tance will not r
26b40 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 esize the memory
26b50 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 .** allocation.)
26b60 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ^.**.** ^SQLite
26b70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 automatically fr
26b80 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ees the memory a
26b90 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 llocated by .**
26ba0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
26bb0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e e_context() when
26bc0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 the aggregate q
26bd0 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a uery concludes..
26be0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
26bf0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 parameter must b
26c00 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a e a copy of the.
26c10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
26c20 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 ext | SQL functi
26c30 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 on context] that
26c40 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 is the first pa
26c50 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
26c60 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 e xStep or xFina
26c70 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 l callback routi
26c80 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ne that implemen
26c90 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 ts the aggregate
26ca0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a .** function..**
26cb0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
26cc0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
26cd0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
26ce0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
26cf0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 the aggregate S
26d00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 QL function is r
26d10 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 unning..*/.void
26d20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 *sqlite3_aggrega
26d30 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 te_context(sqlit
26d40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
26d50 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a nBytes);../*.**
26d60 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 CAPI3REF: User
26d70 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f Data For Functio
26d80 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ns.**.** ^The sq
26d90 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
26da0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
26db0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a rns a copy of.**
26dc0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 the pointer tha
26dd0 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 t was the pUserD
26de0 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 ata parameter (t
26df0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
26e00 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c ).** of the [sql
26e10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
26e20 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b tion()].** and [
26e30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
26e40 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 unction16()] rou
26e50 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 tines that origi
26e60 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 nally.** registe
26e70 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 red the applicat
26e80 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 ion defined func
26e90 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 tion..**.** This
26ea0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 routine must be
26eb0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
26ec0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
26ed0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 which.** the app
26ee0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
26ef0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
26f00 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 ning..*/.void *s
26f10 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
26f20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
26f30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
26f40 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
26f50 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e nnection For Fun
26f60 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 ctions.**.** ^Th
26f70 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e sqlite3_contex
26f80 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e t_db_handle() in
26f90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
26fa0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
26fb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
26fc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
26fd0 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 tion] (the 1st p
26fe0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
26ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
27000 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
27010 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
27020 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
27030 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
27040 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
27050 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
27060 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
27070 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f ned function..*/
27080 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 .sqlite3 *sqlite
27090 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
270a0 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 dle(sqlite3_cont
270b0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
270c0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e PI3REF: Function
270d0 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a Auxiliary Data.
270e0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 **.** The follow
270f0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e ing two function
27100 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 s may be used by
27110 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 scalar SQL func
27120 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f tions to.** asso
27130 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 ciate metadata w
27140 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c ith argument val
27150 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 ues. If the same
27160 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 value is passed
27170 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 to.** multiple
27180 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
27190 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 he same SQL func
271a0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 tion during quer
271b0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 y execution, und
271c0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 er.** some circu
271d0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 mstances the ass
271e0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 ociated metadata
271f0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 may be preserve
27200 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 d. This may.** b
27210 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d e used, for exam
27220 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 ple, to add a re
27230 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e gular-expression
27240 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 matching scalar
27250 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 .** function. Th
27260 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 e compiled versi
27270 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 on of the regula
27280 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 r expression is
27290 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 stored as.** met
272a0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 adata associated
272b0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 with the SQL va
272c0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
272d0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 e regular expres
272e0 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e sion.** pattern.
272f0 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 The compiled r
27300 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f egular expressio
27310 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 n can be reused
27320 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 on multiple.** i
27330 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
27340 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
27350 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 so that the orig
27360 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 inal pattern str
27370 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 ing.** does not
27380 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d need to be recom
27390 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e piled on each in
273a0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 vocation..**.**
273b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
273c0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
273d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
273e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
273f0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 tadata.** associ
27400 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 ated by the sqli
27410 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
27420 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 ) function with
27430 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 the Nth argument
27440 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 .** value to the
27450 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
27460 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e ined function. ^
27470 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 If no metadata h
27480 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 as been ever.**
27490 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 been set for the
274a0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 Nth argument of
274b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f the function, o
274c0 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 r if the corresp
274d0 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 onding.** functi
274e0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 on parameter has
274f0 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 changed since t
27500 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 he meta-data was
27510 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 set,.** then sq
27520 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
27530 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 a() returns a NU
27540 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
27550 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
27560 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
27570 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 erface saves the
27580 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 metadata.** poi
27590 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 nted to by its 3
275a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 rd parameter as
275b0 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 the metadata for
275c0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 the N-th.** arg
275d0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 ument of the app
275e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
275f0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 function. Subs
27600 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 equent.** calls
27610 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 to sqlite3_get_a
27620 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 uxdata() might r
27630 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c eturn this data,
27640 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f if it has.** no
27650 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 t been destroyed
27660 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e ..** ^If it is n
27670 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 ot NULL, SQLite
27680 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 will invoke the
27690 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 destructor.** fu
276a0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 nction given by
276b0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
276c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 r to sqlite3_set
276d0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a _auxdata() on.**
276e0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 the metadata wh
276f0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e en the correspon
27700 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 ding function pa
27710 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a rameter changes.
27720 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 ** or when the S
27730 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
27740 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 pletes, whicheve
27750 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a r comes first..*
27760 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 *.** SQLite is f
27770 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 ree to call the
27780 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 destructor and d
27790 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 rop metadata on
277a0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 any.** parameter
277b0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e of any function
277c0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e at any time. ^
277d0 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 The only guarant
277e0 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 ee is that.** th
277f0 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c e destructor wil
27800 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f l be called befo
27810 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 re the metadata
27820 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a is dropped..**.*
27830 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c * ^(In practice,
27840 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 metadata is pre
27850 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 served between f
27860 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f unction calls fo
27870 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 r.** expressions
27880 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 that are consta
27890 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 nt at compile ti
278a0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 me. This include
278b0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c s literal.** val
278c0 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 ues and [paramet
278d0 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 ers].)^.**.** Th
278e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 ese routines mus
278f0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
27900 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
27910 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
27920 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
27930 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 running..*/.voi
27940 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 d *sqlite3_get_a
27950 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 uxdata(sqlite3_c
27960 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b ontext*, int N);
27970 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 .void sqlite3_se
27980 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
27990 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
279a0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 N, void*, void (
279b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a *)(void*));.../*
279c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
279d0 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 nstants Defining
279e0 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 Special Destruc
279f0 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a tor Behavior.**.
27a00 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 ** These are spe
27a10 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 cial values for
27a20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 the destructor t
27a30 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e hat is passed in
27a40 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c as the.** final
27a50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 argument to rou
27a60 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 tines like [sqli
27a70 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
27a80 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 )]. ^If the des
27a90 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d tructor.** argum
27aa0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 ent is SQLITE_ST
27ab0 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 ATIC, it means t
27ac0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 hat the content
27ad0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 pointer is const
27ae0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 ant.** and will
27af0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 never change. I
27b00 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 t does not need
27b10 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e to be destroyed.
27b20 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 ^The.** SQLITE
27b30 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 _TRANSIENT value
27b40 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
27b50 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b content will lik
27b60 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a ely change in.**
27b70 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 the near future
27b80 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 and that SQLite
27b90 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 should make its
27ba0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
27bb0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 y of.** the cont
27bc0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 ent before retur
27bd0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ning..**.** The
27be0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 typedef is neces
27bf0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f sary to work aro
27c00 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 und problems in
27c10 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 certain.** C++ c
27c20 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 ompilers. See t
27c30 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a icket #2191..*/.
27c40 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 typedef void (*s
27c50 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
27c60 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a r_type)(void*);.
27c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
27c80 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c TATIC ((sql
27c90 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
27ca0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 type)0).#define
27cb0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
27cc0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 ((sqlite3_des
27cd0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 tructor_type)-1)
27ce0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
27cf0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 : Setting The Re
27d00 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 sult Of An SQL F
27d10 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 unction.**.** Th
27d20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
27d30 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 used by the xFu
27d40 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c nc or xFinal cal
27d50 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 lbacks that.** i
27d60 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e mplement SQL fun
27d70 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
27d80 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b gates. See.** [
27d90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
27da0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b unction()] and [
27db0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
27dc0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 unction16()].**
27dd0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
27de0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
27df0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
27e00 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 s work very much
27e10 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d like the [param
27e20 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 eter binding] fa
27e30 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 mily of.** funct
27e40 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e ions used to bin
27e50 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 d values to host
27e60 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 parameters in p
27e70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
27e80 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 ts..** Refer to
27e90 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 the [SQL paramet
27ea0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f er] documentatio
27eb0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c n for additional
27ec0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
27ed0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
27ee0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 _result_blob() i
27ef0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
27f00 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a e result from.**
27f10 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
27f20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
27f30 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 to be the BLOB
27f40 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 whose content is
27f50 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 pointed.** to b
27f60 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 y the second par
27f70 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 ameter and which
27f80 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 is N bytes long
27f90 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a where N is the.
27fa0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 ** third paramet
27fb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
27fc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
27fd0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 roblob() interfa
27fe0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 ces set the resu
27ff0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
28000 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
28010 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
28020 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e a BLOB containin
28030 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 g all zero.** by
28040 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 tes and N bytes
28050 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e in size, where N
28060 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
28070 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
28080 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
28090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
280a0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 uble() interface
280b0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
280c0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
280d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
280e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
280f0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
28100 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a value specified.
28110 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 ** by its 2nd ar
28120 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gument..**.** ^T
28130 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
28140 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
28150 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
28160 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 or16() functions
28170 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d .** cause the im
28180 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 plemented SQL fu
28190 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 nction to throw
281a0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a an exception..**
281b0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 ^SQLite uses th
281c0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 e string pointed
281d0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e to by the.** 2n
281e0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 d parameter of s
281f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
28200 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ror() or sqlite3
28210 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
28220 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 ).** as the text
28230 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 of an error mes
28240 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 sage. ^SQLite i
28250 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 nterprets the er
28260 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 ror.** message s
28270 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 tring from sqlit
28280 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
28290 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c ) as UTF-8. ^SQL
282a0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ite.** interpret
282b0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f s the string fro
282c0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 m sqlite3_result
282d0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 _error16() as UT
282e0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a F-16 in native.*
282f0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e * byte order. ^
28300 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
28310 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
28320 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
28330 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
28340 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
28350 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e is negative then
28360 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 SQLite takes as
28370 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 the error.** me
28380 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 ssage all text u
28390 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 p through the fi
283a0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 rst zero charact
283b0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 er..** ^If the t
283c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
283d0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 o sqlite3_result
283e0 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 _error() or.** s
283f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
28400 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e ror16() is non-n
28410 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c egative then SQL
28420 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d ite takes that m
28430 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f any.** bytes (no
28440 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 t characters) fr
28450 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d om the 2nd param
28460 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f eter as the erro
28470 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 r message..** ^T
28480 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
28490 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
284a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
284b0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e or16().** routin
284c0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 es make a privat
284d0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 e copy of the er
284e0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 ror message text
284f0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 before.** they
28500 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 return. Hence,
28510 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 the calling func
28520 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 tion can dealloc
28530 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 ate or.** modify
28540 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 the text after
28550 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 they return with
28560 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 out harm..** ^Th
28570 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
28580 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 _error_code() fu
28590 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 nction changes t
285a0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a he error code.**
285b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c returned by SQL
285c0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 ite as a result
285d0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 of an error in a
285e0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 function. ^By
285f0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 default,.** the
28600 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 error code is SQ
28610 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 LITE_ERROR. ^A
28620 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 subsequent call
28630 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
28640 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 t_error().** or
28650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
28660 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 rror16() resets
28670 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 the error code t
28680 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a o SQLITE_ERROR..
28690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
286a0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 e3_result_toobig
286b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 () interface cau
286c0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 ses SQLite to th
286d0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 row an error.**
286e0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 indicating that
286f0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 a string or BLOB
28700 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 is to long to r
28710 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 epresent..**.**
28720 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
28730 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 ult_nomem() inte
28740 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c rface causes SQL
28750 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 ite to throw an
28760 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 error.** indicat
28770 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 ing that a memor
28780 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
28790 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 led..**.** ^The
287a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
287b0 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 nt() interface s
287c0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 ets the return v
287d0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 alue.** of the a
287e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
287f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
28800 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 e the 32-bit sig
28810 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 ned integer.** v
28820 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 alue given in th
28830 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a e 2nd argument..
28840 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
28850 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 result_int64() i
28860 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
28870 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
28880 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 * of the applica
28890 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
288a0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 ction to be the
288b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
288c0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 teger.** value g
288d0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 iven in the 2nd
288e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
288f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
28900 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 ult_null() inter
28910 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
28920 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 turn value.** of
28930 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
28940 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
28950 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a n to be NULL..**
28960 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
28970 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 _result_text(),
28980 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
28990 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 ext16(),.** sqli
289a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
289b0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 6le(), and sqlit
289c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
289d0 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a be() interfaces.
289e0 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 ** set the retur
289f0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 n value of the a
28a00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
28a10 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
28a20 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 e.** a text stri
28a30 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 ng which is repr
28a40 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 esented as UTF-8
28a50 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 , UTF-16 native
28a60 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 byte order,.** U
28a70 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 TF-16 little end
28a80 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 ian, or UTF-16 b
28a90 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 ig endian, respe
28aa0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c ctively..** ^SQL
28ab0 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 ite takes the te
28ac0 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 xt result from t
28ad0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 he application f
28ae0 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 rom.** the 2nd p
28af0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 arameter of the
28b00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
28b10 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e ext* interfaces.
28b20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 .** ^If the 3rd
28b30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
28b40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28b50 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
28b60 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c .** is negative,
28b70 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b then SQLite tak
28b80 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 es result text f
28b90 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 rom the 2nd para
28ba0 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 meter.** through
28bb0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
28bc0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 character..** ^I
28bd0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
28be0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
28bf0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
28c00 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 interfaces.** is
28c10 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
28c20 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 hen as many byte
28c30 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 s (not character
28c40 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a s) of the text.*
28c50 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 * pointed to by
28c60 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
28c70 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 r are taken as t
28c80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
28c90 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 efined.** functi
28ca0 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 on result..** ^I
28cb0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
28cc0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
28cd0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
28ce0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 interfaces.** or
28cf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28d00 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 blob is a non-NU
28d10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
28d20 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 SQLite calls th
28d30 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 at.** function a
28d40 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 s the destructor
28d50 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 on the text or
28d60 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e BLOB result when
28d70 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 it has.** finis
28d80 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 hed using that r
28d90 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 esult..** ^If th
28da0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
28db0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
28dc0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
28dd0 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 rfaces or to.**
28de0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
28df0 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 lob is the speci
28e00 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 al constant SQLI
28e10 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 TE_STATIC, then
28e20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 SQLite.** assume
28e30 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 s that the text
28e40 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 or BLOB result i
28e50 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 s in constant sp
28e60 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ace and does not
28e70 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e .** copy the con
28e80 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 tent of the para
28e90 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 meter nor call a
28ea0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 destructor on t
28eb0 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 he content.** wh
28ec0 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 en it has finish
28ed0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 ed using that re
28ee0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 sult..** ^If the
28ef0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
28f00 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
28f10 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
28f20 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 faces.** or sqli
28f30 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
28f40 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
28f50 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 onstant SQLITE_T
28f60 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e RANSIENT.** then
28f70 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 SQLite makes a
28f80 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 copy of the resu
28f90 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 lt into space ob
28fa0 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 tained from.** f
28fb0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
28fc0 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 loc()] before it
28fd0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
28fe0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
28ff0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 ult_value() inte
29000 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
29010 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 esult of.** the
29020 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
29030 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
29040 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a be a copy the.**
29050 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
29060 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
29070 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 ect specified by
29080 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
29090 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c er. ^The.** sql
290a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
290b0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 e() interface ma
290c0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
290d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
290e0 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 ].** so that the
290f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
29100 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 specified in th
29110 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
29120 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 change or.** be
29130 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 deallocated afte
29140 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
29150 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 _value() returns
29160 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a without harm..*
29170 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 * ^A [protected
29180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
29190 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 bject may always
291a0 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 be used where a
291b0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 n.** [unprotecte
291c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
291d0 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 object is requi
291e0 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a red, so either.*
291f0 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 * kind of [sqlit
29200 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
29210 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 can be used wit
29220 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 h this interface
29230 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 ..**.** If these
29240 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 routines are ca
29250 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e lled from within
29260 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 the different t
29270 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 hread.** than th
29280 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 e one containing
29290 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
292a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
292b0 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a n that received.
292c0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
292d0 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 context] pointer
292e0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 , the results ar
292f0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a e undefined..*/.
29300 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
29310 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 ult_blob(sqlite3
29320 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
29330 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 void*, int, voi
29340 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
29350 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
29360 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 t_double(sqlite3
29370 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c _context*, doubl
29380 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 e);.void sqlite3
29390 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 _result_error(sq
293a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
293b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
293c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
293d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 result_error16(s
293e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
293f0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
29400 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
29410 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f _result_error_to
29420 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e obig(sqlite3_con
29430 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c text*);.void sql
29440 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
29450 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f r_nomem(sqlite3_
29460 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 context*);.void
29470 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
29480 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 rror_code(sqlite
29490 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
294a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
294b0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 esult_int(sqlite
294c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
294d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
294e0 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 esult_int64(sqli
294f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 te3_context*, sq
29500 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f lite3_int64);.vo
29510 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
29520 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 t_null(sqlite3_c
29530 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 ontext*);.void s
29540 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
29550 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt(sqlite3_conte
29560 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
29570 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
29580 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
29590 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
295a0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 16(sqlite3_conte
295b0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
295c0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
295d0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
295e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
295f0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 16le(sqlite3_con
29600 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
29610 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 d*, int,void(*)(
29620 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 void*));.void sq
29630 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
29640 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f t16be(sqlite3_co
29650 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
29660 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 id*, int,void(*)
29670 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
29680 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
29690 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 lue(sqlite3_cont
296a0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 ext*, sqlite3_va
296b0 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 lue*);.void sqli
296c0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 te3_result_zerob
296d0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 lob(sqlite3_cont
296e0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f ext*, int n);../
296f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
29700 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 efine New Collat
29710 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a ing Sequences.**
29720 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
29730 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 ons are used to
29740 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f add new collatio
29750 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 n sequences to t
29760 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 he.** [database
29770 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 connection] spec
29780 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 ified as the fir
29790 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a st argument..**.
297a0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 ** ^The name of
297b0 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f the new collatio
297c0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 n sequence is sp
297d0 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 ecified as a UTF
297e0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 -8 string.** for
297f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
29800 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 collation() and
29810 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
29820 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a ollation_v2().**
29830 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 and a UTF-16 st
29840 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 ring for sqlite3
29850 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
29860 6e 31 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 n16(). ^In all c
29870 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 ases.** the name
29880 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68 is passed as th
29890 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f e second functio
298a0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a n argument..**.*
298b0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 * ^The third arg
298c0 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 ument may be one
298d0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 of the constant
298e0 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c s [SQLITE_UTF8],
298f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 .** [SQLITE_UTF1
29900 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 6LE], or [SQLITE
29910 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 _UTF16BE], indic
29920 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 ating that the u
29930 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 ser-supplied.**
29940 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 routine expects
29950 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 to be passed poi
29960 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
29970 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 encoded using U
29980 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 TF-8,.** UTF-16
29990 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f little-endian, o
299a0 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 r UTF-16 big-end
299b0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c ian, respectivel
299c0 79 2e 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64 y. ^The.** third
299d0 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 argument might
299e0 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f also be [SQLITE_
299f0 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61 UTF16] to indica
29a00 74 65 20 74 68 61 74 20 74 68 65 20 72 6f 75 74 te that the rout
29a10 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70 ine.** expects p
29a20 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54 ointers to be UT
29a30 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20 F-16 strings in
29a40 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 the native byte
29a50 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a order, or the.**
29a60 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 argument can be
29a70 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 [SQLITE_UTF16_A
29a80 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a LIGNED] if the.*
29a90 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 * the routine ex
29aa0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 pects pointers t
29ab0 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c o 16-bit word al
29ac0 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a igned strings.**
29ad0 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 of UTF-16 in th
29ae0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
29af0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 der..**.** A poi
29b00 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 nter to the user
29b10 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e supplied routin
29b20 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 e must be passed
29b30 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a as the fifth.**
29b40 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 argument. ^If
29b50 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 it is NULL, this
29b60 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 is the same as
29b70 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c deleting the col
29b80 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e lation.** sequen
29b90 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 ce (so that SQLi
29ba0 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 te cannot call i
29bb0 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e t anymore)..** ^
29bc0 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 Each time the ap
29bd0 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 plication suppli
29be0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 ed function is i
29bf0 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 nvoked, it is pa
29c00 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 ssed.** as its f
29c10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 irst parameter a
29c20 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 copy of the voi
29c30 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 d* passed as the
29c40 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
29c50 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
29c60 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
29c70 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 ) or sqlite3_cre
29c80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
29c90 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 )..**.** ^The re
29ca0 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 maining argument
29cb0 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 s to the applica
29cc0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f tion-supplied ro
29cd0 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 utine are two st
29ce0 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 rings,.** each r
29cf0 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 epresented by a
29d00 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 (length, data) p
29d10 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 air and encoded
29d20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a in the encoding.
29d30 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 ** that was pass
29d40 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 ed as the third
29d50 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 argument when th
29d60 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 e collation sequ
29d70 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 ence was.** regi
29d80 73 74 65 72 65 64 2e 20 20 54 68 65 20 61 70 70 stered. The app
29d90 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 lication defined
29da0 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 collation routi
29db0 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ne should.** ret
29dc0 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 urn negative, ze
29dd0 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 ro or positive i
29de0 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 f the first stri
29df0 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c ng is less than,
29e00 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 .** equal to, or
29e10 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 greater than th
29e20 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e e second string.
29e30 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d i.e. (STRING1 -
29e40 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a STRING2)..**.**
29e50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 ^The sqlite3_cr
29e60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
29e70 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 2() works like s
29e80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
29e90 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 llation().** exc
29ea0 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 ept that it take
29eb0 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d s an extra argum
29ec0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 ent which is a d
29ed0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a estructor for.**
29ee0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 the collation.
29ef0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 ^The destructor
29f00 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 is called when
29f10 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 the collation is
29f20 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e .** destroyed an
29f30 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f d is passed a co
29f40 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 py of the fourth
29f50 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a parameter void*
29f60 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 pointer.** of t
29f70 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 he sqlite3_creat
29f80 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
29f90 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73 ..** ^Collations
29fa0 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 are destroyed w
29fb0 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 hen they are ove
29fc0 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 rridden by later
29fd0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a calls to the.**
29fe0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 collation creat
29ff0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 ion functions or
2a000 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62 when the [datab
2a010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2a020 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 is closed.** usi
2a030 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 ng [sqlite3_clos
2a040 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 e()]..**.** See
2a050 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
2a060 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
2a070 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2a080 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
2a090 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 d16()]..*/.int s
2a0a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2a0b0 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 llation(. sqlit
2a0c0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 e3*, . const ch
2a0d0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e ar *zName, . in
2a0e0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 t eTextRep, . v
2a0f0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f oid*,. int(*xCo
2a100 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
2a110 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
2a120 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b ,const void*).);
2a130 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
2a140 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
2a150 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
2a160 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
2a170 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 me, . int eText
2a180 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 Rep, . void*,.
2a190 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 int(*xCompare)(
2a1a0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
2a1b0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
2a1c0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a void*),. void(*
2a1d0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 xDestroy)(void*)
2a1e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
2a1f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
2a200 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
2a210 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
2a220 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 Name,. int eTex
2a230 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a tRep, . void*,.
2a240 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
2a250 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
2a260 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
2a270 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a void*).);../*.*
2a280 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c * CAPI3REF: Coll
2a290 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c ation Needed Cal
2a2a0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f lbacks.**.** ^To
2a2b0 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f avoid having to
2a2c0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f register all co
2a2d0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
2a2e0 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 s before a datab
2a2f0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 ase.** can be us
2a300 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c ed, a single cal
2a310 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d lback function m
2a320 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 ay be registered
2a330 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 with the.** [da
2a340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2a350 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 n] to be invoked
2a360 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 whenever an und
2a370 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e efined collation
2a380 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 .** sequence is
2a390 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
2a3a0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e ^If the function
2a3b0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 is registered u
2a3c0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
2a3d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
2a3e0 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e d() API,.** then
2a3f0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 it is passed th
2a400 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 e names of undef
2a410 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 ined collation s
2a420 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 equences as stri
2a430 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 ngs.** encoded i
2a440 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c n UTF-8. ^If sql
2a450 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
2a460 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 eeded16() is use
2a470 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 d,.** the names
2a480 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 are passed as UT
2a490 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 F-16 in machine
2a4a0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
2a4b0 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f r..** ^A call to
2a4c0 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e either function
2a4d0 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 replaces the ex
2a4e0 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e isting collation
2a4f0 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b -needed callback
2a500 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 ..**.** ^(When t
2a510 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 he callback is i
2a520 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 nvoked, the firs
2a530 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 t argument passe
2a540 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f d is a copy.** o
2a550 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 f the second arg
2a560 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
2a570 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
2a580 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 d() or.** sqlite
2a590 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
2a5a0 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 ed16(). The sec
2a5b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
2a5c0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
2a5d0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 connection. The
2a5e0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
2a5f0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 is one of [SQLIT
2a600 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 E_UTF8], [SQLITE
2a610 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 _UTF16BE],.** or
2a620 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 [SQLITE_UTF16LE
2a630 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ], indicating th
2a640 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 e most desirable
2a650 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c form of the col
2a660 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e lation.** sequen
2a670 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 ce function requ
2a680 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 ired. The fourt
2a690 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 h parameter is t
2a6a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
2a6b0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 * required colla
2a6c0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e tion sequence.)^
2a6d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 .**.** The callb
2a6e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f ack function sho
2a6f0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 uld register the
2a700 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 desired collati
2a710 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c on using.** [sql
2a720 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
2a730 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 ation()], [sqlit
2a740 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
2a750 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 ion16()], or.**
2a760 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2a770 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e collation_v2()].
2a780 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2a790 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
2a7a0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
2a7b0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 void*, . void(
2a7c0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
2a7d0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 *,int eTextRep,c
2a7e0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 onst char*).);.i
2a7f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 nt sqlite3_colla
2a800 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 tion_needed16(.
2a810 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f sqlite3*, . vo
2a820 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 id*,. void(*)(v
2a830 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e oid*,sqlite3*,in
2a840 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 t eTextRep,const
2a850 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a void*).);../*.*
2a860 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 * Specify the ke
2a870 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 y for an encrypt
2a880 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 ed database. Th
2a890 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c is routine shoul
2a8a0 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 d be.** called r
2a8b0 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 ight after sqlit
2a8c0 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a e3_open()..**.**
2a8d0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 The code to imp
2a8e0 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 lement this API
2a8f0 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 is not available
2a900 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 in the public r
2a910 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c elease.** of SQL
2a920 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ite..*/.int sqli
2a930 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 te3_key(. sqlit
2a940 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2a950 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
2a960 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 abase to be reke
2a970 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 yed */. const v
2a980 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e oid *pKey, int n
2a990 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b Key /* The k
2a9a0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ey */.);../*.**
2a9b0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f Change the key o
2a9c0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 n an open databa
2a9d0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 se. If the curr
2a9e0 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 ent database is
2a9f0 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 not.** encrypted
2aa00 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 , this routine w
2aa10 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 ill encrypt it.
2aa20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e If pNew==0 or n
2aa30 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 New==0, the.** d
2aa40 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 atabase is decry
2aa50 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 pted..**.** The
2aa60 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e code to implemen
2aa70 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f t this API is no
2aa80 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 t available in t
2aa90 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 he public releas
2aaa0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a e.** of SQLite..
2aab0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 */.int sqlite3_r
2aac0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 ekey(. sqlite3
2aad0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2aae0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2aaf0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 se to be rekeyed
2ab00 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
2ab10 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 *pKey, int nKey
2ab20 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 /* The new
2ab30 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a key */.);../*.**
2ab40 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 CAPI3REF: Suspe
2ab50 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 nd Execution For
2ab60 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a A Short Time.**
2ab70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2ab80 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f _sleep() functio
2ab90 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 n causes the cur
2aba0 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 rent thread to s
2abb0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e uspend execution
2abc0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 .** for at least
2abd0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c a number of mil
2abe0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 liseconds specif
2abf0 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d ied in its param
2ac00 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 eter..**.** ^If
2ac10 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
2ac20 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 stem does not su
2ac30 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 pport sleep requ
2ac40 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c ests with.** mil
2ac50 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 lisecond time re
2ac60 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 solution, then t
2ac70 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 he time will be
2ac80 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a rounded up to.**
2ac90 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 the nearest sec
2aca0 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d 62 65 72 ond. ^The number
2acb0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 of milliseconds
2acc0 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c of sleep actual
2acd0 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 ly.** requested
2ace0 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 from the operati
2acf0 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 ng system is ret
2ad00 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 urned..**.** ^SQ
2ad10 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 Lite implements
2ad20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 this interface b
2ad30 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 y calling the xS
2ad40 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 leep().** method
2ad50 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 of the default
2ad60 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
2ad70 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ject..*/.int sql
2ad80 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b ite3_sleep(int);
2ad90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2ada0 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f : Name Of The Fo
2adb0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d lder Holding Tem
2adc0 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a porary Files.**.
2add0 2a 2a 20 5e 49 66 20 74 68 69 73 20 67 6c 6f 62 ** ^If this glob
2ade0 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d al variable is m
2adf0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
2ae00 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 a string which i
2ae10 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 s.** the name of
2ae20 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 a folder (a.k.a
2ae30 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 . directory), th
2ae40 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 en all temporary
2ae50 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 files.** create
2ae60 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e d by SQLite when
2ae70 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 using a built-i
2ae80 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c n [sqlite3_vfs |
2ae90 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 VFS].** will be
2aea0 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 placed in that
2aeb0 64 69 72 65 63 74 6f 72 79 2e 20 20 5e 49 66 20 directory. ^If
2aec0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a this variable.**
2aed0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2aee0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
2aef0 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 performs a searc
2af00 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 h for an appropr
2af10 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 iate.** temporar
2af20 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 y file directory
2af30 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ..**.** It is no
2af40 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f t safe to read o
2af50 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 r modify this va
2af60 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 riable in more t
2af70 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 han one.** threa
2af80 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 d at a time. It
2af90 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
2afa0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 read or modify t
2afb0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 his variable.**
2afc0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 if a [database c
2afd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
2afe0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 ing used at the
2aff0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 same time in a s
2b000 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 eparate.** threa
2b010 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 d..** It is inte
2b020 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 nded that this v
2b030 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f ariable be set o
2b040 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f nce.** as part o
2b050 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 f process initia
2b060 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 lization and bef
2b070 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 ore any SQLite i
2b080 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 nterface.** rout
2b090 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 ines have been c
2b0a0 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 alled and that t
2b0b0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d his variable rem
2b0c0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a ain unchanged.**
2b0d0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a thereafter..**.
2b0e0 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 ** ^The [temp_st
2b0f0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
2b100 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 agma] may modify
2b110 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 this variable a
2b120 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 nd cause.** it t
2b130 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 o point to memor
2b140 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
2b150 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
2b160 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c . ^Furthermore,
2b170 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 .** the [temp_st
2b180 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
2b190 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 agma] always ass
2b1a0 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 umes that any st
2b1b0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 ring.** that thi
2b1c0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 s variable point
2b1d0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 s to is held in
2b1e0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
2b1f0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
2b200 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 3_malloc] and th
2b210 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 e pragma may att
2b220 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 empt to free tha
2b230 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e t memory.** usin
2b240 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d g [sqlite3_free]
2b250 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 ..** Hence, if t
2b260 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 his variable is
2b270 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c modified directl
2b280 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f y, either it sho
2b290 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e uld be.** made N
2b2a0 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 ULL or made to p
2b2b0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f oint to memory o
2b2c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2b2d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a lite3_malloc].**
2b2e0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 or else the use
2b2f0 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 of the [temp_st
2b300 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
2b310 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 agma] should be
2b320 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 avoided..*/.SQLI
2b330 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a TE_EXTERN char *
2b340 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 sqlite3_temp_dir
2b350 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ectory;../*.** C
2b360 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f API3REF: Test Fo
2b370 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f r Auto-Commit Mo
2b380 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 de.** KEYWORDS:
2b390 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 {autocommit mode
2b3a0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c }.**.** ^The sql
2b3b0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d ite3_get_autocom
2b3c0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 mit() interface
2b3d0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
2b3e0 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 or.** zero if t
2b3f0 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 he given databas
2b400 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
2b410 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 or is not in aut
2b420 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a ocommit mode,.**
2b430 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 respectively.
2b440 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 ^Autocommit mode
2b450 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c is on by defaul
2b460 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 t..** ^Autocommi
2b470 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c t mode is disabl
2b480 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 ed by a [BEGIN]
2b490 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 statement..** ^A
2b4a0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 utocommit mode i
2b4b0 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 s re-enabled by
2b4c0 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 a [COMMIT] or [R
2b4d0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 OLLBACK]..**.**
2b4e0 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 If certain kinds
2b4f0 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 of errors occur
2b500 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 on a statement
2b510 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 within a multi-s
2b520 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e tatement.** tran
2b530 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 saction (errors
2b540 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 including [SQLIT
2b550 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 E_FULL], [SQLITE
2b560 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c _IOERR],.** [SQL
2b570 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c ITE_NOMEM], [SQL
2b580 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b ITE_BUSY], and [
2b590 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
2b5a0 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 ]) then the.** t
2b5b0 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 ransaction might
2b5c0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
2b5d0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
2b5e0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a The only way to.
2b5f0 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 ** find out whet
2b600 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d her SQLite autom
2b610 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
2b620 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 back the transac
2b630 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e tion after.** an
2b640 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 error is to use
2b650 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a this function..
2b660 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 **.** If another
2b670 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 thread changes
2b680 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 the autocommit s
2b690 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 tatus of the dat
2b6a0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
2b6b0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 ion while this r
2b6c0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e outine is runnin
2b6d0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 g, then the retu
2b6e0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 rn value.** is u
2b6f0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 ndefined..*/.int
2b700 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 sqlite3_get_aut
2b710 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a ocommit(sqlite3*
2b720 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2b730 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 EF: Find The Dat
2b740 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 abase Handle Of
2b750 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
2b760 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ment.**.** ^The
2b770 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
2b780 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 e interface retu
2b790 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 rns the [databas
2b7a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
2b7b0 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 ndle.** to which
2b7c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2b7d0 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e tement] belongs.
2b7e0 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 ^The [database
2b7f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
2b800 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
2b810 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 te3_db_handle is
2b820 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
2b830 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
2b840 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20 ** that was the
2b850 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a first argument.*
2b860 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
2b870 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2b880 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 call (or its var
2b890 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 iants) that was
2b8a0 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 used to.** creat
2b8b0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 e the statement
2b8c0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 in the first pla
2b8d0 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a ce..*/.sqlite3 *
2b8e0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
2b8f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 e(sqlite3_stmt*)
2b900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2b910 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 F: Find the next
2b920 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2b930 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ent.**.** ^This
2b940 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2b950 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
2b960 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 he next [prepare
2b970 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 d statement] aft
2b980 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f er.** pStmt asso
2b990 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
2b9a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2b9b0 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 tion] pDb. ^If
2b9c0 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a pStmt is NULL.**
2b9d0 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 then this inter
2b9e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
2b9f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 ointer to the fi
2ba00 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 rst prepared sta
2ba10 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 tement.** associ
2ba20 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 ated with the da
2ba30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2ba40 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 n pDb. ^If no p
2ba50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2ba60 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 t.** satisfies t
2ba70 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 he conditions of
2ba80 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 this routine, i
2ba90 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a t returns NULL..
2baa0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 **.** The [datab
2bab0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2bac0 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 pointer D in a c
2bad0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
2bae0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 e3_next_stmt(D,S
2baf0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f )] must refer to
2bb00 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
2bb10 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
2bb20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 and in particula
2bb30 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 r must not be a
2bb40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f NULL pointer..*/
2bb50 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 .sqlite3_stmt *s
2bb60 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 qlite3_next_stmt
2bb70 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 (sqlite3 *pDb, s
2bb80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2bb90 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2bba0 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 3REF: Commit And
2bbb0 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 Rollback Notifi
2bbc0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 cation Callbacks
2bbd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2bbe0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
2bbf0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
2bc00 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
2bc10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 .** function to
2bc20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
2bc30 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
2bc40 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 n is [COMMIT | c
2bc50 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 ommitted]..** ^A
2bc60 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
2bc70 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
2bc80 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ll to sqlite3_co
2bc90 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 mmit_hook().** f
2bca0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
2bcb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2bcc0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
2bcd0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
2bce0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 ollback_hook() i
2bcf0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
2bd00 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a rs a callback.**
2bd10 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2bd20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
2bd30 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
2bd40 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f s [ROLLBACK | ro
2bd50 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e lled back]..** ^
2bd60 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 Any callback set
2bd70 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 by a previous c
2bd80 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 all to sqlite3_r
2bd90 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a ollback_hook().*
2bda0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 * for the same d
2bdb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2bdc0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e on is overridden
2bdd0 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 ..** ^The pArg a
2bde0 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 rgument is passe
2bdf0 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
2be00 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 callback..** ^I
2be10 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f f the callback o
2be20 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 n a commit hook
2be30 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
2be40 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 non-zero,.** th
2be50 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 en the commit is
2be60 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 converted into
2be70 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a a rollback..**.*
2be80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
2be90 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 ommit_hook(D,C,P
2bea0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f ) and sqlite3_ro
2beb0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c llback_hook(D,C,
2bec0 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 P) functions.**
2bed0 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 return the P arg
2bee0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 ument from the p
2bef0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 revious call of
2bf00 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
2bf10 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 n.** on the same
2bf20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2bf30 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c ction] D, or NUL
2bf40 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 L for.** the fir
2bf50 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 st call for each
2bf60 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a function on D..
2bf70 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 **.** The callba
2bf80 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ck implementatio
2bf90 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e n must not do an
2bfa0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
2bfb0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
2bfc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2bfd0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
2bfe0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 the callback. A
2bff0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f ny actions.** to
2c000 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
2c010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2c020 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 must be deferred
2c030 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 until after the
2c040 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f .** completion o
2c050 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 f the [sqlite3_s
2c060 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 tep()] call that
2c070 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 triggered the c
2c080 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c ommit.** or roll
2c090 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 back hook in the
2c0a0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a first place..**
2c0b0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
2c0c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2c0d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
2c0e0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
2c0f0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
2c100 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
2c110 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
2c120 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
2c130 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
2c140 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 **.** ^Registeri
2c150 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 ng a NULL functi
2c160 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 on disables the
2c170 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
2c180 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 ^When the commit
2c190 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 hook callback r
2c1a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a outine returns z
2c1b0 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 ero, the [COMMIT
2c1c0 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 ].** operation i
2c1d0 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e s allowed to con
2c1e0 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 tinue normally.
2c1f0 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 ^If the commit
2c200 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 hook.** returns
2c210 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 non-zero, then t
2c220 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 he [COMMIT] is c
2c230 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 onverted into a
2c240 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e [ROLLBACK]..** ^
2c250 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f The rollback hoo
2c260 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 k is invoked on
2c270 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 a rollback that
2c280 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 results from a c
2c290 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 ommit.** hook re
2c2a0 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f turning non-zero
2c2b0 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 , just as it wou
2c2c0 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f ld be with any o
2c2d0 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a ther rollback..*
2c2e0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 *.** ^For the pu
2c2f0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 rposes of this A
2c300 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f PI, a transactio
2c310 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 n is said to hav
2c320 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 e been.** rolled
2c330 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c back if an expl
2c340 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 icit "ROLLBACK"
2c350 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 statement is exe
2c360 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 cuted, or.** an
2c370 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 error or constra
2c380 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d int causes an im
2c390 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 plicit rollback
2c3a0 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 to occur..** ^Th
2c3b0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 e rollback callb
2c3c0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b ack is not invok
2c3d0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 ed if a transact
2c3e0 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 ion is.** automa
2c3f0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
2c400 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 ack because the
2c410 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2c420 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
2c430 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 * ^The rollback
2c440 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 callback is not
2c450 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 invoked if a tra
2c460 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 nsaction is.** r
2c470 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 olled back becau
2c480 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c se a commit call
2c490 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f back returned no
2c4a0 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 n-zero..**.** Se
2c4b0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
2c4c0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
2c4d0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f )] interface..*/
2c4e0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 .void *sqlite3_c
2c4f0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 ommit_hook(sqlit
2c500 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 e3*, int(*)(void
2c510 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 *), void*);.void
2c520 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 *sqlite3_rollba
2c530 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a ck_hook(sqlite3*
2c540 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a , void(*)(void *
2c550 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
2c560 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
2c570 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 Change Notifica
2c580 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a tion Callbacks.*
2c590 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2c5a0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 3_update_hook()
2c5b0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
2c5c0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
2c5d0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 unction.** with
2c5e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2c5f0 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 nnection] identi
2c600 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 fied by the firs
2c610 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f t argument.** to
2c620 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
2c630 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 ever a row is up
2c640 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
2c650 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e or deleted..** ^
2c660 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 Any callback set
2c670 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 by a previous c
2c680 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 all to this func
2c690 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 tion.** for the
2c6a0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
2c6b0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 nnection is over
2c6c0 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ridden..**.** ^T
2c6d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
2c6e0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
2c6f0 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 to the function
2c700 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 to invoke when a
2c710 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 .** row is updat
2c720 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 ed, inserted or
2c730 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 deleted..** ^The
2c740 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
2c750 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
2c760 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
2c770 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a third argument.
2c780 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 ** to sqlite3_up
2c790 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 date_hook()..**
2c7a0 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c ^The second call
2c7b0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 back argument is
2c7c0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
2c7d0 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 INSERT], [SQLITE
2c7e0 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 _DELETE],.** or
2c7f0 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c [SQLITE_UPDATE],
2c800 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
2c810 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 e operation that
2c820 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c caused the call
2c830 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e back.** to be in
2c840 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 voked..** ^The t
2c850 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
2c860 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 arguments to the
2c870 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
2c880 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 n pointers to th
2c890 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e e.** database an
2c8a0 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e d table name con
2c8b0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 taining the affe
2c8c0 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 cted row..** ^Th
2c8d0 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b e final callback
2c8e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
2c8f0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 e [rowid] of the
2c900 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 row..** ^In the
2c910 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 case of an upda
2c920 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 te, this is the
2c930 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 [rowid] after th
2c940 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 e update takes p
2c950 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 lace..**.** ^(Th
2c960 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 e update hook is
2c970 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 not invoked whe
2c980 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 n internal syste
2c990 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 m tables are.**
2c9a0 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 modified (i.e. s
2c9b0 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 qlite_master and
2c9c0 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 sqlite_sequence
2c9d0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 ).)^.**.** ^In t
2c9e0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 he current imple
2c9f0 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 mentation, the u
2ca00 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 pdate hook.** is
2ca10 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 not invoked whe
2ca20 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f n duplication ro
2ca30 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 ws are deleted b
2ca40 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 ecause of an.**
2ca50 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f [ON CONFLICT | O
2ca60 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 N CONFLICT REPLA
2ca70 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f CE] clause. ^No
2ca80 72 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 r is the update
2ca90 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 hook.** invoked
2caa0 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 when rows are de
2cab0 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 leted using the
2cac0 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 [truncate optimi
2cad0 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 zation]..** The
2cae0 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e exceptions defin
2caf0 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 ed in this parag
2cb00 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 raph might chang
2cb10 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a e in a future.**
2cb20 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
2cb30 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 te..**.** The up
2cb40 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d date hook implem
2cb50 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f entation must no
2cb60 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
2cb70 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
2cb80 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
2cb90 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
2cba0 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 nvoked the updat
2cbb0 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 e hook. Any act
2cbc0 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 ions.** to modif
2cbd0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 y the database c
2cbe0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 onnection must b
2cbf0 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c e deferred until
2cc00 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f after the.** co
2cc10 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 mpletion of the
2cc20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2cc30 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
2cc40 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 ered the update
2cc50 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 hook..** Note th
2cc60 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
2cc70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
2cc80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
2cc90 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
2cca0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
2ccb0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
2ccc0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
2ccd0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
2cce0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 agraph..**.** ^T
2ccf0 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 he sqlite3_updat
2cd00 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 e_hook(D,C,P) fu
2cd10 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e nction.** return
2cd20 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 s the P argument
2cd30 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f from the previo
2cd40 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 us call.** on th
2cd50 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
2cd60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 connection] D,
2cd70 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 or NULL for.** t
2cd80 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e he first call on
2cd90 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c D..**.** See al
2cda0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
2cdb0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 commit_hook()] a
2cdc0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c nd [sqlite3_roll
2cdd0 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 back_hook()].**
2cde0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 interfaces..*/.v
2cdf0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 oid *sqlite3_upd
2ce00 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 ate_hook(. sqli
2ce10 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 te3*, . void(*)
2ce20 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 (void *,int ,cha
2ce30 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 r const *,char c
2ce40 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 onst *,sqlite3_i
2ce50 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 nt64),. void*.)
2ce60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2ce70 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 F: Enable Or Dis
2ce80 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 able Shared Page
2ce90 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f r Cache.** KEYWO
2cea0 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 RDS: {shared cac
2ceb0 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 he}.**.** ^(This
2cec0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 routine enables
2ced0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
2cee0 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 sharing of the
2cef0 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a database cache.*
2cf00 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 * and schema dat
2cf10 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 a structures bet
2cf20 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 ween [database c
2cf30 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e onnection | conn
2cf40 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 ections].** to t
2cf50 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
2cf60 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 . Sharing is ena
2cf70 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 bled if the argu
2cf80 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 ment is true.**
2cf90 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 and disabled if
2cfa0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 the argument is
2cfb0 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e false.)^.**.** ^
2cfc0 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 Cache sharing is
2cfd0 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 enabled and dis
2cfe0 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 abled for an ent
2cff0 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 ire process..**
2d000 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 This is a change
2d010 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 as of SQLite ve
2d020 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 rsion 3.5.0. In
2d030 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f prior versions o
2d040 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 f SQLite,.** sha
2d050 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 ring was enabled
2d060 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 or disabled for
2d070 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 each thread sep
2d080 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e arately..**.** ^
2d090 28 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69 (The cache shari
2d0a0 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 ng mode set by t
2d0b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 his interface ef
2d0c0 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 fects all subseq
2d0d0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f uent.** calls to
2d0e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
2d0f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
2d100 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c _v2()], and [sql
2d110 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a ite3_open16()]..
2d120 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 ** Existing data
2d130 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
2d140 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 continue use th
2d150 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a e sharing mode.*
2d160 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 * that was in ef
2d170 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 fect at the time
2d180 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 they were opene
2d190 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 d.)^.**.** ^(Thi
2d1a0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
2d1b0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 s [SQLITE_OK] if
2d1c0 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 shared cache wa
2d1d0 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 s enabled or dis
2d1e0 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 abled.** success
2d1f0 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f fully. An [erro
2d200 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
2d210 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e ned otherwise.)^
2d220 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 .**.** ^Shared c
2d230 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 ache is disabled
2d240 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 by default. But
2d250 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e this might chan
2d260 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 ge in.** future
2d270 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
2d280 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e te. Application
2d290 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 s that care abou
2d2a0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 t shared.** cach
2d2b0 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 e setting should
2d2c0 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 set it explicit
2d2d0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c ly..**.** See Al
2d2e0 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 so: [SQLite Sha
2d2f0 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a red-Cache Mode].
2d300 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 */.int sqlite3_e
2d310 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 nable_shared_cac
2d320 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 he(int);../*.**
2d330 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 CAPI3REF: Attemp
2d340 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d t To Free Heap M
2d350 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 emory.**.** ^The
2d360 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 sqlite3_release
2d370 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 _memory() interf
2d380 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
2d390 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 free N bytes.**
2d3a0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 of heap memory b
2d3b0 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e y deallocating n
2d3c0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d on-essential mem
2d3d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a ory allocations.
2d3e0 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 ** held by the d
2d3f0 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e atabase library.
2d400 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 Memory used t
2d410 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 o cache database
2d420 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 .** pages to imp
2d430 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 rove performance
2d440 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f is an example o
2d450 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 f non-essential
2d460 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 memory..** ^sqli
2d470 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2d480 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 ry() returns the
2d490 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2d4a0 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c actually freed,
2d4b0 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 .** which might
2d4c0 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 be more or less
2d4d0 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 than the amount
2d4e0 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e requested..*/.in
2d4f0 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 t sqlite3_releas
2d500 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a e_memory(int);..
2d510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2d520 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f Impose A Limit O
2d530 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a n Heap Size.**.*
2d540 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
2d550 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 oft_heap_limit()
2d560 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 interface place
2d570 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 s a "soft" limit
2d580 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e .** on the amoun
2d590 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 t of heap memory
2d5a0 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c that may be all
2d5b0 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 ocated by SQLite
2d5c0 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 69 6e 74 65 ..** ^If an inte
2d5d0 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rnal allocation
2d5e0 69 73 20 72 65 71 75 65 73 74 65 64 20 74 68 61 is requested tha
2d5f0 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 t would exceed t
2d600 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 he.** soft heap
2d610 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f limit, [sqlite3_
2d620 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
2d630 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 ] is invoked one
2d640 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 or.** more time
2d650 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d s to free up som
2d660 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 e space before t
2d670 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 he allocation is
2d680 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a performed..**.*
2d690 2a 20 5e 54 68 65 20 6c 69 6d 69 74 20 69 73 20 * ^The limit is
2d6a0 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 called "soft", b
2d6b0 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 ecause if [sqlit
2d6c0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
2d6d0 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 y()].** cannot f
2d6e0 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d ree sufficient m
2d6f0 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 emory to prevent
2d700 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 the limit from
2d710 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a being exceeded,.
2d720 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 ** the memory is
2d730 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 allocated anywa
2d740 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e y and the curren
2d750 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 t operation proc
2d760 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 6e eeds..**.** ^A n
2d770 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 egative or zero
2d780 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e value for N mean
2d790 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 s that there is
2d7a0 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d no soft heap lim
2d7b0 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 it and.** [sqlit
2d7c0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
2d7d0 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 y()] will only b
2d7e0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 e called when me
2d7f0 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65 mory is exhauste
2d800 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 d..** ^The defau
2d810 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 lt value for the
2d820 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
2d830 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 is zero..**.**
2d840 5e 28 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 ^(SQLite makes a
2d850 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 best effort to
2d860 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 honor the soft h
2d870 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 eap limit..** Bu
2d880 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 t if the soft he
2d890 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 ap limit cannot
2d8a0 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 be honored, exec
2d8b0 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f ution will.** co
2d8c0 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 ntinue without e
2d8d0 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 rror or notifica
2d8e0 74 69 6f 6e 2e 29 5e 20 20 54 68 69 73 20 69 73 tion.)^ This is
2d8f0 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 why the limit i
2d900 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 s.** called a "s
2d910 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 oft" limit. It
2d920 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 is advisory only
2d930 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f ..**.** Prior to
2d940 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2d950 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 3.5.0, this rout
2d960 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 ine only constra
2d970 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a ined the memory.
2d980 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 ** allocated by
2d990 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 a single thread
2d9a0 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 - the same threa
2d9b0 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 d in which this
2d9c0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e routine.** runs.
2d9d0 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 Beginning with
2d9e0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2d9f0 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 3.5.0, the soft
2da00 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a heap limit is.**
2da10 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 applied to all
2da20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c threads. The val
2da30 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 ue specified for
2da40 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
2da50 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 imit.** is an up
2da60 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 per bound on the
2da70 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c total memory al
2da80 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c location for all
2da90 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 threads. In.**
2daa0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 version 3.5.0 th
2dab0 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e ere is no mechan
2dac0 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 ism for limiting
2dad0 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20 the heap usage
2dae0 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 for.** individua
2daf0 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f l threads..*/.vo
2db00 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f id sqlite3_soft_
2db10 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b heap_limit(int);
2db20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2db30 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 : Extract Metada
2db40 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d ta About A Colum
2db50 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a n Of A Table.**.
2db60 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
2db70 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 returns metadat
2db80 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 a about a specif
2db90 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 ic column of a s
2dba0 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 pecific.** datab
2dbb0 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 ase table access
2dbc0 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b ible using the [
2dbd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2dbe0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 ion] handle.** p
2dbf0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
2dc00 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 st function argu
2dc10 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ment..**.** ^The
2dc20 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 column is ident
2dc30 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 ified by the sec
2dc40 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 ond, third and f
2dc50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 ourth parameters
2dc60 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 to.** this func
2dc70 74 69 6f 6e 2e 20 5e 28 54 68 65 20 73 65 63 6f tion. ^(The seco
2dc80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
2dc90 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 either the name
2dca0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
2dcb0 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c ** (i.e. "main",
2dcc0 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 "temp" or an at
2dcd0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 tached database)
2dce0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
2dcf0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 specified.** tab
2dd00 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 le or NULL. If i
2dd10 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 t is NULL, then
2dd20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 all attached dat
2dd30 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 abases are searc
2dd40 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 hed.** for the t
2dd50 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 able using the s
2dd60 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 ame algorithm us
2dd70 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 ed by the databa
2dd80 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 se engine to.**
2dd90 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 resolve unqualif
2dda0 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 ied table refere
2ddb0 6e 63 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 nces.)^.**.** ^T
2ddc0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 he third and fou
2ddd0 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 rth parameters t
2dde0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 o this function
2ddf0 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e are the table an
2de00 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 d column.** name
2de10 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 of the desired
2de20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 column, respecti
2de30 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 vely. Neither of
2de40 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 these parameter
2de50 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c s.** may be NULL
2de60 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 ..**.** ^Metadat
2de70 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 a is returned by
2de80 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 writing to the
2de90 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 memory locations
2dea0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 passed as the 5
2deb0 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 th.** and subseq
2dec0 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 uent parameters
2ded0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
2dee0 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 . ^Any of these
2def0 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 arguments may be
2df00 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 .** NULL, in whi
2df10 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 ch case the corr
2df20 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e esponding elemen
2df30 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 t of metadata is
2df40 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 omitted..**.**
2df50 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ^(<blockquote>.*
2df60 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
2df70 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
2df80 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 Parameter <th>
2df90 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c Output<br>Type <
2dfa0 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e th> Description
2dfb0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 .**.** <tr><td>
2dfc0 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 5th <td> const c
2dfd0 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 har* <td> Data t
2dfe0 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ype.** <tr><td>
2dff0 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 6th <td> const c
2e000 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f har* <td> Name o
2e010 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 f default collat
2e020 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 ion sequence.**
2e030 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 <tr><td> 7th <td
2e040 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 > int <t
2e050 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d d> True if colum
2e060 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c n has a NOT NULL
2e070 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c constraint.** <
2e080 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e tr><td> 8th <td>
2e090 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
2e0a0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
2e0b0 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 is part of the
2e0c0 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c PRIMARY KEY.** <
2e0d0 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e tr><td> 9th <td>
2e0e0 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
2e0f0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
2e100 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 is [AUTOINCREME
2e110 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a NT].** </table>.
2e120 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e ** </blockquote>
2e130 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 )^.**.** ^The me
2e140 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 mory pointed to
2e150 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 by the character
2e160 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
2e170 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 ed for the.** de
2e180 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 claration type a
2e190 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 nd collation seq
2e1a0 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f uence is valid o
2e1b0 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 nly until the ne
2e1c0 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e xt.** call to an
2e1d0 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e y SQLite API fun
2e1e0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 ction..**.** ^If
2e1f0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 the specified t
2e200 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 able is actually
2e210 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 a view, an [err
2e220 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
2e230 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 rned..**.** ^If
2e240 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f the specified co
2e250 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c lumn is "rowid",
2e260 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 "oid" or "_rowi
2e270 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 d_" and an.** [I
2e280 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
2e290 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 EY] column has b
2e2a0 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 een explicitly d
2e2b0 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 eclared, then th
2e2c0 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 e output.** para
2e2d0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 meters are set f
2e2e0 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c or the explicitl
2e2f0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d y declared colum
2e300 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 n. ^(If there is
2e310 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c no.** explicitl
2e320 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 y declared [INTE
2e330 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d GER PRIMARY KEY]
2e340 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 column, then th
2e350 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 e output.** para
2e360 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 meters are set a
2e370 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
2e380 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 <pre>.** da
2e390 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 ta type: "INTEGE
2e3a0 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 R".** collat
2e3b0 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 ion sequence: "B
2e3c0 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f INARY".** no
2e3d0 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 t null: 0.**
2e3e0 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a primary key: 1.
2e3f0 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 ** auto incr
2e400 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 ement: 0.** </pr
2e410 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 e>)^.**.** ^(Thi
2e420 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c s function may l
2e430 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 oad one or more
2e440 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 schemas from dat
2e450 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 abase files. If
2e460 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 an.** error occu
2e470 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 rs during this p
2e480 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 rocess, or if th
2e490 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c e requested tabl
2e4a0 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 e or column.** c
2e4b0 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 annot be found,
2e4c0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
2e4d0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
2e4e0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
2e4f0 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 left.** in the
2e500 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2e510 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 tion] (to be ret
2e520 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c rieved using sql
2e530 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 ite3_errmsg()).)
2e540 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 ^.**.** ^This AP
2e550 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 I is only availa
2e560 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 ble if the libra
2e570 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 ry was compiled
2e580 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
2e590 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d ITE_ENABLE_COLUM
2e5a0 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 N_METADATA] C-pr
2e5b0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f eprocessor symbo
2e5c0 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e l defined..*/.in
2e5d0 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f t sqlite3_table_
2e5e0 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 column_metadata(
2e5f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2e600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2e610 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e * Connection han
2e620 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
2e630 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 har *zDbName,
2e640 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
2e650 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f name or NULL */
2e660 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2e670 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f TableName, /
2e680 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a * Table name */.
2e690 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 const char *zC
2e6a0 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a olumnName, /*
2e6b0 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a Column name */.
2e6c0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 char const **p
2e6d0 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a zDataType, /*
2e6e0 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 OUTPUT: Declare
2e6f0 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 d data type */.
2e700 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a char const **pz
2e710 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 CollSeq, /*
2e720 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f OUTPUT: Collatio
2e730 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 n sequence name
2e740 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 */. int *pNotNu
2e750 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ll,
2e760 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 /* OUTPUT: True
2e770 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e if NOT NULL con
2e780 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a straint exists *
2e790 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 /. int *pPrimar
2e7a0 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 yKey,
2e7b0 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 /* OUTPUT: True
2e7c0 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f if column part o
2e7d0 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 f PK */. int *p
2e7e0 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 Autoinc
2e7f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
2e800 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
2e810 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e is auto-incremen
2e820 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t */.);../*.** C
2e830 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e API3REF: Load An
2e840 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a Extension.**.**
2e850 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 ^This interface
2e860 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 loads an SQLite
2e870 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 extension libra
2e880 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 ry from the name
2e890 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 d file..**.** ^T
2e8a0 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f he sqlite3_load_
2e8b0 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 extension() inte
2e8c0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
2e8d0 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c o load an.** SQL
2e8e0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 ite extension li
2e8f0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 brary contained
2e900 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c in the file zFil
2e910 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e e..**.** ^The en
2e920 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 try point is zPr
2e930 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 oc..** ^zProc ma
2e940 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 y be 0, in which
2e950 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f case the name o
2e960 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e f the entry poin
2e970 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f t.** defaults to
2e980 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 "sqlite3_extens
2e990 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 ion_init"..** ^T
2e9a0 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f he sqlite3_load_
2e9b0 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 extension() inte
2e9c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a rface returns.**
2e9d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
2e9e0 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c success and [SQL
2e9f0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f ITE_ERROR] if so
2ea00 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f mething goes wro
2ea10 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 ng..** ^If an er
2ea20 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 ror occurs and p
2ea30 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 zErrMsg is not 0
2ea40 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 , then the.** [s
2ea50 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
2ea60 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 nsion()] interfa
2ea70 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 ce shall attempt
2ea80 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 to.** fill *pzE
2ea90 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 rrMsg with error
2eaa0 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 message text st
2eab0 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a ored in memory.*
2eac0 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 * obtained from
2ead0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
2eae0 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 )]. The calling
2eaf0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 function.** shou
2eb00 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d ld free this mem
2eb10 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b ory by calling [
2eb20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
2eb30 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f .**.** ^Extensio
2eb40 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 n loading must b
2eb50 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a e enabled using.
2eb60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 ** [sqlite3_enab
2eb70 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
2eb80 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 n()] prior to ca
2eb90 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a lling this API,.
2eba0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 ** otherwise an
2ebb0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
2ebc0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 turned..**.** Se
2ebd0 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 e also the [load
2ebe0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c _extension() SQL
2ebf0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 function]..*/.i
2ec00 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f nt sqlite3_load_
2ec10 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c extension(. sql
2ec20 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
2ec30 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 /* Load the e
2ec40 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 xtension into th
2ec50 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e is database conn
2ec60 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 ection */. cons
2ec70 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 t char *zFile,
2ec80 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
2ec90 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 shared library
2eca0 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e containing exten
2ecb0 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 sion */. const
2ecc0 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 char *zProc,
2ecd0 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 /* Entry point.
2ece0 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 Derived from zF
2ecf0 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 ile if 0 */. ch
2ed00 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 ar **pzErrMsg
2ed10 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 /* Put error
2ed20 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 message here if
2ed30 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a not 0 */.);../*
2ed40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
2ed50 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
2ed60 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e Extension Loadin
2ed70 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e g.**.** ^So as n
2ed80 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 ot to open secur
2ed90 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 ity holes in old
2eda0 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 er applications
2edb0 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 that are.** unpr
2edc0 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 epared to deal w
2edd0 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f ith extension lo
2ede0 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 ading, and as a
2edf0 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 means of disabli
2ee00 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 ng.** extension
2ee10 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 loading while ev
2ee20 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e aluating user-en
2ee30 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 tered SQL, the f
2ee40 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 ollowing API.**
2ee50 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 is provided to t
2ee60 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 urn the [sqlite3
2ee70 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
2ee80 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 )] mechanism on
2ee90 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e and off..**.** ^
2eea0 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e Extension loadin
2eeb0 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 g is off by defa
2eec0 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 ult. See ticket
2eed0 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 #1863..** ^Call
2eee0 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 the sqlite3_enab
2eef0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
2ef00 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 n() routine with
2ef10 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 onoff==1.** to
2ef20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c turn extension l
2ef30 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 oading on and ca
2ef40 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 ll it with onoff
2ef50 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 ==0 to turn.** i
2ef60 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e t back off again
2ef70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2ef80 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 _enable_load_ext
2ef90 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a ension(sqlite3 *
2efa0 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a db, int onoff);.
2efb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2efc0 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c Automatically L
2efd0 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e oad An Extension
2efe0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 s.**.** ^This AP
2eff0 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 I can be invoked
2f000 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 at program star
2f010 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 tup in order to
2f020 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 register.** one
2f030 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c or more statical
2f040 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 ly linked extens
2f050 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 ions that will b
2f060 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 e available.** t
2f070 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 o all new [datab
2f080 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
2f090 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 ..**.** ^(This r
2f0a0 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 outine stores a
2f0b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 pointer to the e
2f0c0 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 xtension entry p
2f0d0 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 oint.** in an ar
2f0e0 72 61 79 20 74 68 61 74 20 69 73 20 6f 62 74 61 ray that is obta
2f0f0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
2f100 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 e3_malloc()]. T
2f110 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 hat memory.** is
2f120 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 deallocated by
2f130 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 [sqlite3_reset_a
2f140 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d uto_extension()]
2f150 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 .)^.**.** ^This
2f160 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
2f170 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 rs an extension
2f180 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 entry point that
2f190 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 is.** automatic
2f1a0 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 65 ally invoked whe
2f1b0 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61 74 never a new [dat
2f1c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2f1d0 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65 64 20 75 ].** is opened u
2f1e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 sing [sqlite3_op
2f1f0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
2f200 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72 open16()],.** or
2f210 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
2f220 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70 6c 69 63 2()]..** ^Duplic
2f230 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 ate extensions a
2f240 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 re detected so c
2f250 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 alling this rout
2f260 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 ine.** multiple
2f270 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 times with the s
2f280 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 ame extension is
2f290 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 20 5e 41 harmless..** ^A
2f2a0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
2f2b0 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 ons apply across
2f2c0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f all threads..*/
2f2d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 .int sqlite3_aut
2f2e0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 o_extension(void
2f2f0 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 (*xEntryPoint)(
2f300 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void));../*.** C
2f310 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
2f320 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 utomatic Extensi
2f330 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a on Loading.**.**
2f340 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ^(This function
2f350 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 disables all pr
2f360 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 eviously registe
2f370 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a red automatic.**
2f380 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 49 74 20 extensions. It
2f390 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
2f3a0 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a t of all prior.*
2f3b0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f * [sqlite3_auto_
2f3c0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c extension()] cal
2f3d0 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 ls.)^.**.** ^Thi
2f3e0 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 s function disab
2f3f0 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65 78 les automatic ex
2f400 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 tensions in all
2f410 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 threads..*/.void
2f420 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 sqlite3_reset_a
2f430 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f uto_extension(vo
2f440 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 id);../*.******
2f450 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 EXPERIMENTAL - s
2f460 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
2f470 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 without notice
2f480 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a **************.*
2f490 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 *.** The interfa
2f4a0 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 ce to the virtua
2f4b0 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 l-table mechanis
2f4c0 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 m is currently c
2f4d0 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 onsidered.** to
2f4e0 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e be experimental.
2f4f0 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 The interface
2f500 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 might change in
2f510 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 incompatible way
2f520 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 s..** If this is
2f530 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 a problem for y
2f540 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 ou, do not use t
2f550 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 he interface at
2f560 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a this time..**.**
2f570 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 When the virtua
2f580 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 l-table mechanis
2f590 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 m stabilizes, we
2f5a0 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 will declare th
2f5b0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 e.** interface f
2f5c0 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 ixed, support it
2f5d0 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 indefinitely, a
2f5e0 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 nd remove this c
2f5f0 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a omment..*/../*.*
2f600 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65 * Structures use
2f610 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c d by the virtual
2f620 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 table interface
2f630 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
2f640 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 ct sqlite3_vtab
2f650 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 sqlite3_vtab;.ty
2f660 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
2f670 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 ite3_index_info
2f680 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
2f690 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 fo;.typedef stru
2f6a0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f ct sqlite3_vtab_
2f6b0 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 cursor sqlite3_v
2f6c0 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 tab_cursor;.type
2f6d0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
2f6e0 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 e3_module sqlite
2f6f0 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 3_module;../*.**
2f700 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 CAPI3REF: Virtu
2f710 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a al Table Object.
2f720 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
2f730 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 ite3_module {vir
2f740 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
2f750 65 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 e}.** EXPERIMENT
2f760 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 AL.**.** This st
2f770 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d ructure, sometim
2f780 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76 es called a a "v
2f790 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
2f7a0 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 ule", .** define
2f7b0 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 s the implementa
2f7c0 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 tion of a [virtu
2f7d0 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a al tables]. .**
2f7e0 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 This structure
2f7f0 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 consists mostly
2f800 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 of methods for t
2f810 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a he module..**.**
2f820 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c ^A virtual tabl
2f830 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 e module is crea
2f840 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 ted by filling i
2f850 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a n a persistent.*
2f860 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
2f870 69 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 is structure and
2f880 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 passing a point
2f890 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 er to that insta
2f8a0 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 nce.** to [sqlit
2f8b0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
2f8c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2f8d0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 create_module_v2
2f8e0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 ()]..** ^The reg
2f8f0 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e istration remain
2f900 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 s valid until it
2f910 20 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 is replaced by
2f920 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d a different.** m
2f930 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 odule or until t
2f940 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
2f950 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e nection] closes.
2f960 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a The content.**
2f970 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 of this structu
2f980 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e re must not chan
2f990 67 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72 ge while it is r
2f9a0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a egistered with.*
2f9b0 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 * any database c
2f9c0 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 onnection..*/.st
2f9d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 ruct sqlite3_mod
2f9e0 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 ule {. int iVer
2f9f0 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 sion;. int (*xC
2fa00 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c reate)(sqlite3*,
2fa10 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 void *pAux,.
2fa20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 int
2fa30 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 argc, const char
2fa40 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 *const*argv,.
2fa50 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c sql
2fa60 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 ite3_vtab **ppVT
2fa70 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 ab, char**);. i
2fa80 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 nt (*xConnect)(s
2fa90 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 qlite3*, void *p
2faa0 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 Aux,.
2fab0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f int argc, co
2fac0 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a nst char *const*
2fad0 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 argv,.
2fae0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 sqlite3_vta
2faf0 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 b **ppVTab, char
2fb00 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 **);. int (*xBe
2fb10 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 stIndex)(sqlite3
2fb20 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 _vtab *pVTab, sq
2fb30 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f lite3_index_info
2fb40 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 *);. int (*xDis
2fb50 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 connect)(sqlite3
2fb60 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
2fb70 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 int (*xDestroy)
2fb80 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
2fb90 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
2fba0 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 Open)(sqlite3_vt
2fbb0 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 ab *pVTab, sqlit
2fbc0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a e3_vtab_cursor *
2fbd0 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e *ppCursor);. in
2fbe0 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 t (*xClose)(sqli
2fbf0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a te3_vtab_cursor*
2fc00 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 );. int (*xFilt
2fc10 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 er)(sqlite3_vtab
2fc20 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 _cursor*, int id
2fc30 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 xNum, const char
2fc40 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 *idxStr,.
2fc50 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
2fc60 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 gc, sqlite3_valu
2fc70 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 e **argv);. int
2fc80 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 (*xNext)(sqlite
2fc90 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 3_vtab_cursor*);
2fca0 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 . int (*xEof)(s
2fcb0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
2fcc0 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 or*);. int (*xC
2fcd0 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 olumn)(sqlite3_v
2fce0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c tab_cursor*, sql
2fcf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
2fd00 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f nt);. int (*xRo
2fd10 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 wid)(sqlite3_vta
2fd20 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 b_cursor*, sqlit
2fd30 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 e3_int64 *pRowid
2fd40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 );. int (*xUpda
2fd50 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 te)(sqlite3_vtab
2fd60 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 *, int, sqlite3
2fd70 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 _value **, sqlit
2fd80 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 e3_int64 *);. i
2fd90 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c nt (*xBegin)(sql
2fda0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
2fdb0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 );. int (*xSync
2fdc0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
2fdd0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
2fde0 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 xCommit)(sqlite3
2fdf0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
2fe00 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b int (*xRollback
2fe10 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
2fe20 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
2fe30 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 xFindFunction)(s
2fe40 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 qlite3_vtab *pVt
2fe50 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f ab, int nArg, co
2fe60 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
2fe70 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
2fe80 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a void (**
2fe90 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f pxFunc)(sqlite3_
2fea0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
2feb0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
2fec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2fed0 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 void **ppA
2fee0 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 rg);. int (*xRe
2fef0 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 name)(sqlite3_vt
2ff00 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 ab *pVtab, const
2ff10 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b char *zNew);.};
2ff20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2ff30 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 : Virtual Table
2ff40 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 Indexing Informa
2ff50 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 tion.** KEYWORDS
2ff60 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f : sqlite3_index_
2ff70 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 49 4d 45 info.** EXPERIME
2ff80 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 NTAL.**.** The s
2ff90 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 qlite3_index_inf
2ffa0 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 o structure and
2ffb0 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65 its substructure
2ffc0 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 s is used to.**
2ffd0 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e pass information
2ffe0 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 into and receiv
2fff0 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d e the reply from
30000 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 the [xBestIndex
30010 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 ].** method of a
30020 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
30030 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 module]. The fi
30040 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 elds under **Inp
30050 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a uts** are the.**
30060 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 inputs to xBest
30070 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 Index and are re
30080 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 ad-only. xBestI
30090 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 ndex inserts its
300a0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f .** results into
300b0 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a the **Outputs**
300c0 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e fields..**.** ^
300d0 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 (The aConstraint
300e0 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 [] array records
300f0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f WHERE clause co
30100 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 nstraints of the
30110 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 form:.**.** <pr
30120 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 e>column OP expr
30130 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 </pre>.**.** whe
30140 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b re OP is =, <
30150 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f , <=, >, o
30160 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 54 68 65 r >=.)^ ^The
30170 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 particular oper
30180 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 ator is.** store
30190 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 d in aConstraint
301a0 5b 5d 2e 6f 70 2e 20 20 5e 54 68 65 20 69 6e 64 [].op. ^The ind
301b0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
301c0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a is stored in.**
301d0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 aConstraint[].i
301e0 43 6f 6c 75 6d 6e 2e 20 20 5e 28 61 43 6f 6e 73 Column. ^(aCons
301f0 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 traint[].usable
30200 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a is TRUE if the.*
30210 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 * expr on the ri
30220 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 ght-hand side ca
30230 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 n be evaluated (
30240 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e and thus the con
30250 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 straint.** is us
30260 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 able) and false
30270 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a if it cannot.)^.
30280 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d **.** ^The optim
30290 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c izer automatical
302a0 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 ly inverts terms
302b0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 of the form "ex
302c0 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a pr OP column".**
302d0 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 and makes other
302e0 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 simplifications
302f0 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c to the WHERE cl
30300 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d ause in an attem
30310 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 pt to.** get as
30320 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 many WHERE claus
30330 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 e terms into the
30340 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 form shown abov
30350 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a e as possible..*
30360 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 * ^The aConstrai
30370 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 nt[] array only
30380 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c reports WHERE cl
30390 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 ause terms in th
303a0 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 e correct.** for
303b0 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 m that refer to
303c0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 the particular v
303d0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 irtual table bei
303e0 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a ng queried..**.*
303f0 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 * ^Information a
30400 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 bout the ORDER B
30410 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 Y clause is stor
30420 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d ed in aOrderBy[]
30430 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 ..** ^Each term
30440 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f of aOrderBy reco
30450 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 rds a column of
30460 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
30470 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b use..**.** The [
30480 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 xBestIndex] meth
30490 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f od must fill aCo
304a0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 nstraintUsage[]
304b0 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e with information
304c0 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 .** about what p
304d0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 arameters to pas
304e0 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e s to xFilter. ^
304f0 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 If argvIndex>0 t
30500 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 hen.** the right
30510 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 -hand side of th
30520 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
30530 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 aConstraint[] is
30540 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e evaluated.** an
30550 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 d becomes the ar
30560 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 gvIndex-th entry
30570 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20 in argv. ^(If
30580 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
30590 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 [].omit.** is tr
305a0 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e ue, then the con
305b0 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d straint is assum
305c0 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 ed to be fully h
305d0 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a andled by the.**
305e0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 virtual table a
305f0 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 nd is not checke
30600 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 d again by SQLit
30610 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e.)^.**.** ^The
30620 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 idxNum and idxPt
30630 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 r values are rec
30640 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 orded and passed
30650 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 into the.** [xF
30660 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a ilter] method..*
30670 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 * ^[sqlite3_free
30680 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66 ()] is used to f
30690 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 6e ree idxPtr if an
306a0 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e 65 d only iff.** ne
306b0 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 edToFreeIdxPtr i
306c0 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 s true..**.** ^T
306d0 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d he orderByConsum
306e0 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 ed means that ou
306f0 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 tput from [xFilt
30700 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c er]/[xNext] will
30710 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 occur in.** the
30720 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 correct order t
30730 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 o satisfy the OR
30740 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f DER BY clause so
30750 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 that no separat
30760 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 e.** sorting ste
30770 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a p is required..*
30780 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 *.** ^The estima
30790 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 tedCost value is
307a0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 an estimate of
307b0 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e the cost of doin
307c0 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 g the.** particu
307d0 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 lar lookup. A f
307e0 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 ull scan of a ta
307f0 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 ble with N entri
30800 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a es should have.*
30810 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 * a cost of N.
30820 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 A binary search
30830 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 of a table of N
30840 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 entries should h
30850 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 ave a.** cost of
30860 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c approximately l
30870 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 og(N)..*/.struct
30880 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
30890 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 nfo {. /* Input
308a0 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 s */. int nCons
308b0 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 traint;
308c0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 /* Number of e
308d0 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 ntries in aConst
308e0 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 raint */. struc
308f0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
30900 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 constraint {.
30910 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 int iColumn;
30920 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 /* C
30930 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 olumn on left-ha
30940 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 nd side of const
30950 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e raint */. un
30960 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 signed char op;
30970 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 /* Const
30980 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a raint operator *
30990 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 /. unsigned
309a0 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 char usable;
309b0 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 /* True if this
309c0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 constraint is u
309d0 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e sable */. in
309e0 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 t iTermOffset;
309f0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 /* Used
30a00 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 internally - xBe
30a10 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 stIndex should i
30a20 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 gnore */. } *aC
30a30 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 onstraint;
30a40 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f /* Table o
30a50 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 f WHERE clause c
30a60 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 onstraints */.
30a70 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 int nOrderBy;
30a80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
30a90 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e mber of terms in
30aa0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c the ORDER BY cl
30ab0 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 ause */. struct
30ac0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f sqlite3_index_o
30ad0 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e rderby {. in
30ae0 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 t iColumn;
30af0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d /* Colum
30b00 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 n number */.
30b10 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 unsigned char d
30b20 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 esc; /* Tr
30b30 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 ue for DESC. Fa
30b40 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a lse for ASC. */.
30b50 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 } *aOrderBy;
30b60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
30b70 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 The ORDER BY cla
30b80 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 use */. /* Outp
30b90 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 uts */. struct
30ba0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f sqlite3_index_co
30bb0 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b nstraint_usage {
30bc0 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 . int argvInd
30bd0 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a ex; /*
30be0 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 if >0, constrai
30bf0 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 nt is part of ar
30c00 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f gv to xFilter */
30c10 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 . unsigned ch
30c20 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a ar omit; /*
30c30 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 Do not code a t
30c40 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e est for this con
30c50 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a straint */. } *
30c60 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
30c70 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 ;. int idxNum;
30c80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
30c90 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f * Number used to
30ca0 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e identify the in
30cb0 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 dex */. char *i
30cc0 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 dxStr;
30cd0 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 /* String, p
30ce0 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 ossibly obtained
30cf0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
30d00 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 lloc */. int ne
30d10 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 edToFreeIdxStr;
30d20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 /* Free idx
30d30 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 Str using sqlite
30d40 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 3_free() if true
30d50 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 */. int orderB
30d60 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 yConsumed;
30d70 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 /* True if outp
30d80 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 ut is already or
30d90 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c dered */. doubl
30da0 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b e estimatedCost;
30db0 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 /* Estimat
30dc0 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 ed cost of using
30dd0 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d this index */.}
30de0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ;.#define SQLITE
30df0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
30e00 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e T_EQ 2.#defin
30e10 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
30e20 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 ONSTRAINT_GT
30e30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
30e40 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
30e50 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e T_LE 8.#defin
30e60 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
30e70 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 ONSTRAINT_LT
30e80 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 16.#define SQLIT
30e90 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 E_INDEX_CONSTRAI
30ea0 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 NT_GE 32.#def
30eb0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
30ec0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 _CONSTRAINT_MATC
30ed0 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 H 64../*.** CAPI
30ee0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 3REF: Register A
30ef0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 Virtual Table I
30f00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
30f10 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
30f20 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
30f30 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 nes are used to
30f40 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b register a new [
30f50 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f virtual table mo
30f60 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e dule] name..** ^
30f70 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 Module names mus
30f80 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 t be registered
30f90 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 before.** creati
30fa0 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 ng a new [virtua
30fb0 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 l table] using t
30fc0 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 he module, or be
30fd0 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 fore using a.**
30fe0 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 preexisting [vir
30ff0 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 tual table] for
31000 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a the module..**.*
31010 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 * ^The module na
31020 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64 me is registered
31030 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 on the [databas
31040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
31050 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 ecified.** by th
31060 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
31070 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 r. ^The name of
31080 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 the module is g
31090 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 iven by the .**
310a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
310b0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 . ^The third pa
310c0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
310d0 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 nter to.** the i
310e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
310f0 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 the [virtual ta
31100 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e ble module]. ^
31110 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 The fourth.** pa
31120 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 rameter is an ar
31130 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64 bitrary client d
31140 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ata pointer that
31150 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 is passed throu
31160 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b gh.** into the [
31170 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 xCreate] and [xC
31180 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 onnect] methods
31190 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 of the virtual t
311a0 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 able module.** w
311b0 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61 hen a new virtua
311c0 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65 l table is be be
311d0 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72 ing created or r
311e0 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a einitialized..**
311f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
31200 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 _create_module_v
31210 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61 2() interface ha
31220 73 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65 s a fifth parame
31230 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ter which.** is
31240 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 a pointer to a d
31250 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 estructor for th
31260 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20 e pClientData.
31270 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 ^SQLite will.**
31280 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
31290 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 uctor function (
312a0 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c if it is not NUL
312b0 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a L) when SQLite.*
312c0 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 * no longer need
312d0 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 s the pClientDat
312e0 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 a pointer. ^The
312f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
31300 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 module().** inte
31310 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c rface is equival
31320 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ent to sqlite3_c
31330 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 reate_module_v2(
31340 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a ) with a NULL.**
31350 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a destructor..*/.
31360 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
31370 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TAL int sqlite3_
31380 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 create_module(.
31390 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
313a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
313b0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e QLite connection
313c0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 to register mod
313d0 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f ule with */. co
313e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
313f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 /* Name
31400 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a of the module *
31410 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 /. const sqlite
31420 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 3_module *p, /
31430 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 * Methods for th
31440 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f e module */. vo
31450 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 id *pClientData
31460 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 /* Clie
31470 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 nt data for xCre
31480 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a ate/xConnect */.
31490 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 );.SQLITE_EXPERI
314a0 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
314b0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
314c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
314d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
314e0 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e /* SQLite conn
314f0 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 ection to regist
31500 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a er module with *
31510 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
31520 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f zName, /
31530 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f * Name of the mo
31540 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 dule */. const
31550 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a sqlite3_module *
31560 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 p, /* Methods
31570 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a for the module *
31580 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e /. void *pClien
31590 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f tData, /
315a0 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f * Client data fo
315b0 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 r xCreate/xConne
315c0 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 ct */. void(*xD
315d0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 estroy)(void*)
315e0 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 /* Module des
315f0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e tructor function
31600 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
31610 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
31620 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f Table Instance O
31630 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
31640 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a S: sqlite3_vtab.
31650 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
31660 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 **.** Every [vir
31670 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
31680 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f e] implementatio
31690 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 n uses a subclas
316a0 73 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a s.** of this obj
316b0 65 63 74 20 74 6f 20 64 65 73 63 72 69 62 65 20 ect to describe
316c0 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 a particular ins
316d0 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 tance.** of the
316e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e [virtual table].
316f0 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 Each subclass
31700 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f will.** be tailo
31710 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 red to the speci
31720 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 fic needs of the
31730 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e module implemen
31740 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 tation..** The p
31750 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 urpose of this s
31760 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 uperclass is to
31770 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 define certain f
31780 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a ields that are.*
31790 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 * common to all
317a0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 module implement
317b0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 ations..**.** ^V
317c0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 irtual tables me
317d0 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e thods can set an
317e0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 error message b
317f0 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a y assigning a.**
31800 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
31810 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
31820 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 printf()] to zEr
31830 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f rMsg. The metho
31840 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 d should.** take
31850 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 care that any p
31860 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 rior string is f
31870 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 reed by a call t
31880 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
31890 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 )].** prior to a
318a0 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 ssigning a new s
318b0 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 tring to zErrMsg
318c0 2e 20 20 5e 41 66 74 65 72 20 74 68 65 20 65 72 . ^After the er
318d0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 ror message.** i
318e0 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 s delivered up t
318f0 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 o the client app
31900 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 lication, the st
31910 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 ring will be aut
31920 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 omatically.** fr
31930 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 eed by sqlite3_f
31940 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 ree() and the zE
31950 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c rrMsg field will
31960 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 be zeroed..*/.s
31970 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
31980 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c ab {. const sql
31990 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f ite3_module *pMo
319a0 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f dule; /* The mo
319b0 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 dule for this vi
319c0 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 rtual table */.
319d0 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 int nRef;
319e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
319f0 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 /* NO LONGER US
31a00 45 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 ED */. char *zE
31a10 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 rrMsg;
31a20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 /* Error
31a30 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 message from sq
31a40 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 lite3_mprintf()
31a50 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 */. /* Virtual
31a60 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 table implementa
31a70 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 tions will typic
31a80 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f ally add additio
31a90 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b nal fields */.};
31aa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31ab0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 : Virtual Table
31ac0 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a Cursor Object.**
31ad0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
31ae0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b e3_vtab_cursor {
31af0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 virtual table cu
31b00 72 73 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d rsor}.** EXPERIM
31b10 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 ENTAL.**.** Ever
31b20 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 y [virtual table
31b30 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 module] impleme
31b40 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 ntation uses a s
31b50 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a ubclass of the.*
31b60 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 * following stru
31b70 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 cture to describ
31b80 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 e cursors that p
31b90 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a oint into the.**
31ba0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
31bb0 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a and are used.**
31bc0 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 to loop through
31bd0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
31be0 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 le. Cursors are
31bf0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 created using t
31c00 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
31c10 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f odule.xOpen | xO
31c20 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 pen] method of t
31c30 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 he module and ar
31c40 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 e destroyed.** b
31c50 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d y the [sqlite3_m
31c60 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 odule.xClose | x
31c70 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 Close] method.
31c80 43 75 72 73 6f 72 73 20 61 72 65 20 75 73 65 64 Cursors are used
31c90 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c .** by the [xFil
31ca0 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b ter], [xNext], [
31cb0 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d xEof], [xColumn]
31cc0 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d , and [xRowid] m
31cd0 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 ethods.** of the
31ce0 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d module. Each m
31cf0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 odule implementa
31d00 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 tion will define
31d10 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 .** the content
31d20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 of a cursor stru
31d30 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 cture to suit it
31d40 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a s own needs..**.
31d50 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 ** This supercla
31d60 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 ss exists in ord
31d70 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 er to define fie
31d80 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f lds of the curso
31d90 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f r that.** are co
31da0 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c mmon to all impl
31db0 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a ementations..*/.
31dc0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
31dd0 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 tab_cursor {. s
31de0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 qlite3_vtab *pVt
31df0 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 ab; /* Virt
31e00 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 ual table of thi
31e10 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a s cursor */. /*
31e20 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 Virtual table i
31e30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 mplementations w
31e40 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 ill typically ad
31e50 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 d additional fie
31e60 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a lds */.};../*.**
31e70 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 CAPI3REF: Decla
31e80 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 re The Schema Of
31e90 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 A Virtual Table
31ea0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
31eb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 .**.** ^The [xCr
31ec0 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e eate] and [xConn
31ed0 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 ect] methods of
31ee0 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 a.** [virtual ta
31ef0 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c ble module] call
31f00 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a this interface.
31f10 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 ** to declare th
31f20 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 e format (the na
31f30 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 mes and datatype
31f40 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 s of the columns
31f50 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 ) of.** the virt
31f60 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 ual tables they
31f70 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 implement..*/.SQ
31f80 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
31f90 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 L int sqlite3_de
31fa0 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 clare_vtab(sqlit
31fb0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 e3*, const char
31fc0 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *zSQL);../*.** C
31fd0 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 API3REF: Overloa
31fe0 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 d A Function For
31ff0 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 A Virtual Table
32000 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
32010 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c .**.** ^(Virtual
32020 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 tables can prov
32030 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 ide alternative
32040 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
32050 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 of functions.**
32060 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 using the [xFind
32070 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 Function] method
32080 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c of the [virtual
32090 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 table module].
320a0 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 .** But global
320b0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 versions of thos
320c0 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d e functions.** m
320d0 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 ust exist in ord
320e0 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 er to be overloa
320f0 64 65 64 2e 29 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ded.).**.** ^(Th
32100 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 is API makes sur
32110 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 e a global versi
32120 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e on of a function
32130 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c with a particul
32140 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e ar.** name and n
32150 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 umber of paramet
32160 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 ers exists. If
32170 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e no such function
32180 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 exists.** befor
32190 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61 e this API is ca
321a0 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 lled, a new func
321b0 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e tion is created.
321c0 29 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 )^ ^The impleme
321d0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 ntation.** of th
321e0 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 e new function a
321f0 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 lways causes an
32200 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 exception to be
32210 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 thrown. So.** t
32220 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 he new function
32230 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 is not good for
32240 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 anything by itse
32250 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a lf. Its only.**
32260 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 purpose is to b
32270 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 e a placeholder
32280 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 function that ca
32290 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a n be overloaded.
322a0 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c ** by a [virtual
322b0 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 table]..*/.SQLI
322c0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
322d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 int sqlite3_over
322e0 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 load_function(sq
322f0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 lite3*, const ch
32300 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 ar *zFuncName, i
32310 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a nt nArg);../*.**
32320 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 The interface t
32330 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 o the virtual-ta
32340 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 ble mechanism de
32350 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 fined above (bac
32360 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d k up.** to a com
32370 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 ment remarkably
32380 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 similar to this
32390 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c one) is currentl
323a0 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 y considered.**
323b0 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 to be experiment
323c0 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 al. The interfa
323d0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 ce might change
323e0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 in incompatible
323f0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 ways..** If this
32400 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f is a problem fo
32410 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 r you, do not us
32420 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 e the interface
32430 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a at this time..**
32440 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 .** When the vir
32450 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 tual-table mecha
32460 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c nism stabilizes,
32470 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 we will declare
32480 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 the.** interfac
32490 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 e fixed, support
324a0 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 it indefinitely
324b0 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 , and remove thi
324c0 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a s comment..**.**
324d0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 **** EXPERIMENTA
324e0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 L - subject to c
324f0 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f hange without no
32500 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a tice ***********
32510 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 ***.*/../*.** CA
32520 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 PI3REF: A Handle
32530 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 To An Open BLOB
32540 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 .** KEYWORDS: {B
32550 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f LOB handle} {BLO
32560 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a B handles}.**.**
32570 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
32580 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 this object repr
32590 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 esents an open B
325a0 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 LOB on which.**
325b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
325c0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
325d0 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 BLOB I/O] can b
325e0 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 e performed..**
325f0 5e 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 ^Objects of this
32600 20 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65 type are create
32610 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c d by [sqlite3_bl
32620 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e ob_open()].** an
32630 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b d destroyed by [
32640 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
32650 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b se()]..** ^The [
32660 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 sqlite3_blob_rea
32670 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 d()] and [sqlite
32680 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 3_blob_write()]
32690 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 interfaces.** ca
326a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 n be used to rea
326b0 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c d or write small
326c0 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 subsections of
326d0 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 the BLOB..** ^Th
326e0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
326f0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 bytes()] interfa
32700 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 ce returns the s
32710 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ize of the BLOB
32720 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 in bytes..*/.typ
32730 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
32740 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 te3_blob sqlite3
32750 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 _blob;../*.** CA
32760 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 PI3REF: Open A B
32770 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e LOB For Incremen
32780 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 tal I/O.**.** ^(
32790 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 This interfaces
327a0 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 opens a [BLOB ha
327b0 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 ndle | handle] t
327c0 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 o the BLOB locat
327d0 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f ed.** in row iRo
327e0 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d w, column zColum
327f0 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 n, table zTable
32800 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b in database zDb;
32810 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 .** in other wor
32820 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f ds, the same BLO
32830 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 B that would be
32840 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a selected by:.**.
32850 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 ** <pre>.**
32860 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 SELECT zColumn F
32870 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 ROM zDb.zTable W
32880 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 HERE [rowid] = i
32890 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e Row;.** </pre>)^
328a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
328b0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 lags parameter i
328c0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
328d0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 the BLOB is ope
328e0 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 ned for read.**
328f0 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 and write access
32900 2e 20 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f . ^If it is zero
32910 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 , the BLOB is op
32920 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 ened for read ac
32930 63 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 cess..** ^It is
32940 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 not possible to
32950 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 open a column th
32960 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e at is part of an
32970 20 69 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72 index or primar
32980 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 y .** key for wr
32990 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 iting. ^If [fore
329a0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 ign key constrai
329b0 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 nts] are enabled
329c0 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 , it is .** not
329d0 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e possible to open
329e0 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 a column that i
329f0 73 20 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69 s part of a [chi
32a00 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 ld key] for writ
32a10 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 ing..**.** ^Note
32a20 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 that the databa
32a30 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 se name is not t
32a40 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 he filename that
32a50 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 contains.** the
32a60 20 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61 database but ra
32a70 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 ther the symboli
32a80 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 c name of the da
32a90 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 tabase that.** a
32aa0 70 70 65 61 72 73 20 61 66 74 65 72 20 74 68 65 ppears after the
32ab0 20 41 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e AS keyword when
32ac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
32ad0 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 connected using
32ae0 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 [ATTACH]..** ^F
32af0 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 or the main data
32b00 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 base file, the d
32b10 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 atabase name is
32b20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 "main"..** ^For
32b30 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 TEMP tables, the
32b40 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 database name i
32b50 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 s "temp"..**.**
32b60 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 ^(On success, [S
32b70 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 QLITE_OK] is ret
32b80 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 urned and the ne
32b90 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 w [BLOB handle]
32ba0 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f is written.** to
32bb0 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 *ppBlob. Otherw
32bc0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ise an [error co
32bd0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 de] is returned
32be0 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 and *ppBlob is s
32bf0 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 et.** to be a nu
32c00 6c 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a ll pointer.)^.**
32c10 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^This function
32c20 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 sets the [databa
32c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 se connection] e
32c40 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
32c50 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 ssage.** accessi
32c60 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 ble via [sqlite3
32c70 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 _errcode()] and
32c80 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
32c90 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a )] and related.*
32ca0 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f * functions. ^No
32cb0 74 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 te that the *ppB
32cc0 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 lob variable is
32cd0 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a always initializ
32ce0 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 ed in a.** way t
32cf0 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 hat makes it saf
32d00 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c e to invoke [sql
32d10 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 ite3_blob_close(
32d20 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a )] on *ppBlob.**
32d30 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
32d40 68 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 he success or fa
32d50 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f ilure of this ro
32d60 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 utine..**.** ^(I
32d70 66 20 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 f the row that a
32d80 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 BLOB handle poi
32d90 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 nts to is modifi
32da0 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 ed by an.** [UPD
32db0 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 ATE], [DELETE],
32dc0 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 or by [ON CONFLI
32dd0 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 CT] side-effects
32de0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f .** then the BLO
32df0 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b B handle is mark
32e00 65 64 20 61 73 20 22 65 78 70 69 72 65 64 22 2e ed as "expired".
32e10 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 .** This is true
32e20 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f if any column o
32e30 66 20 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 f the row is cha
32e40 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c nged, even a col
32e50 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 umn.** other tha
32e60 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c n the one the BL
32e70 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 OB handle is ope
32e80 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c n on.)^.** ^Call
32e90 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c s to [sqlite3_bl
32ea0 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b ob_read()] and [
32eb0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 sqlite3_blob_wri
32ec0 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 te()] for.** a e
32ed0 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 xpired BLOB hand
32ee0 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 le fail with an
32ef0 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b return code of [
32f00 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a SQLITE_ABORT]..*
32f10 2a 20 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74 * ^(Changes writ
32f20 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 ten into a BLOB
32f30 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f prior to the BLO
32f40 42 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e B expiring are n
32f50 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 62 ot.** rollback b
32f60 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e y the expiration
32f70 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 of the BLOB. S
32f80 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c uch changes will
32f90 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 eventually.** c
32fa0 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 ommit if the tra
32fb0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 nsaction continu
32fc0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e es to completion
32fd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 .)^.**.** ^Use t
32fe0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
32ff0 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
33000 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 ace to determine
33010 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 the size of.**
33020 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e the opened blob.
33030 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61 ^The size of a
33040 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 blob may not be
33050 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 changed by this
33060 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 .** interface.
33070 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d Use the [UPDATE]
33080 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 SQL command to
33090 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 change the size
330a0 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a of a.** blob..**
330b0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
330c0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
330d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
330e0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
330f0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a )] interfaces.**
33100 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 and the built-i
33110 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c n [zeroblob] SQL
33120 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 function can be
33130 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 used, if desire
33140 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 d,.** to create
33150 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 an empty, zero-f
33160 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 illed blob in wh
33170 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 ich to read or w
33180 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 rite using.** th
33190 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
331a0 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 .** To avoid a r
331b0 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 esource leak, ev
331c0 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 ery open [BLOB h
331d0 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 andle] should ev
331e0 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 entually.** be r
331f0 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c eleased by a cal
33200 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c l to [sqlite3_bl
33210 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a ob_close()]..*/.
33220 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
33230 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 _open(. sqlite3
33240 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 *,. const char
33250 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *zDb,. const ch
33260 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f ar *zTable,. co
33270 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d nst char *zColum
33280 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 n,. sqlite3_int
33290 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 64 iRow,. int f
332a0 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f lags,. sqlite3_
332b0 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b blob **ppBlob.);
332c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
332d0 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 : Close A BLOB H
332e0 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f andle.**.** ^Clo
332f0 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f ses an open [BLO
33300 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a B handle]..**.**
33310 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 ^Closing a BLOB
33320 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 shall cause the
33330 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 current transac
33340 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a tion to commit.*
33350 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e * if there are n
33360 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e o other BLOBs, n
33370 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 o pending prepar
33380 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 ed statements, a
33390 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 nd the.** databa
333a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
333b0 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 in [autocommit
333c0 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e mode]..** ^If an
333d0 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 y writes were ma
333e0 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 de to the BLOB,
333f0 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 they might be he
33400 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 ld in cache.** u
33410 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f ntil the close o
33420 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 peration if they
33430 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a will fit..**.**
33440 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 ^(Closing the B
33450 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 LOB often forces
33460 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 the changes.**
33470 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 out to disk and
33480 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 so if any I/O er
33490 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 rors occur, they
334a0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 will likely occ
334b0 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d ur.** at the tim
334c0 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 e when the BLOB
334d0 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 is closed. Any
334e0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 errors that occu
334f0 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 r during.** clos
33500 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 ing are reported
33510 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 as a non-zero r
33520 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a eturn value.)^.*
33530 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 *.** ^(The BLOB
33540 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 is closed uncond
33550 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e itionally. Even
33560 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 if this routine
33570 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 returns.** an e
33580 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 rror code, the B
33590 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f LOB is still clo
335a0 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 sed.)^.**.** ^Ca
335b0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 lling this routi
335c0 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 ne with a null p
335d0 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20 ointer (such as
335e0 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 would be returne
335f0 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64 d.** by a failed
33600 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
33610 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 3_blob_open()])
33620 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f is a harmless no
33630 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 -op..*/.int sqli
33640 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 te3_blob_close(s
33650 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a qlite3_blob *);.
33660 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33670 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 Return The Size
33680 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 Of An Open BLOB
33690 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 .**.** ^Returns
336a0 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 the size in byte
336b0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 s of the BLOB ac
336c0 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 cessible via the
336d0 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c .** successfull
336e0 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 y opened [BLOB h
336f0 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e andle] in its on
33700 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 ly argument. ^T
33710 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 he.** incrementa
33720 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 l blob I/O routi
33730 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 nes can only rea
33740 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 d or overwriting
33750 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f existing.** blo
33760 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 b content; they
33770 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 cannot change th
33780 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 e size of a blob
33790 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
337a0 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 tine only works
337b0 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c on a [BLOB handl
337c0 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 e] which has bee
337d0 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 n created.** by
337e0 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 a prior successf
337f0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
33800 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d te3_blob_open()]
33810 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e and which has n
33820 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 ot.** been close
33830 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c d by [sqlite3_bl
33840 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 ob_close()]. Pa
33850 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 ssing any other
33860 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f pointer in.** to
33870 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 this routine re
33880 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e sults in undefin
33890 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 ed and probably
338a0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 undesirable beha
338b0 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c vior..*/.int sql
338c0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 ite3_blob_bytes(
338d0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b sqlite3_blob *);
338e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
338f0 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d : Read Data From
33900 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e A BLOB Incremen
33910 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 tally.**.** ^(Th
33920 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 is function is u
33930 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 sed to read data
33940 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 from an open [B
33950 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f LOB handle] into
33960 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 a.** caller-sup
33970 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 plied buffer. N
33980 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 bytes of data ar
33990 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 e copied into bu
339a0 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 ffer Z.** from t
339b0 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 he open BLOB, st
339c0 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 arting at offset
339d0 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a iOffset.)^.**.*
339e0 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 * ^If offset iOf
339f0 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 fset is less tha
33a00 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 n N bytes from t
33a10 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c he end of the BL
33a20 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 OB,.** [SQLITE_E
33a30 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 RROR] is returne
33a40 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 d and no data is
33a50 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 read. ^If N or
33a60 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c iOffset is.** l
33a70 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b ess than zero, [
33a80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 SQLITE_ERROR] is
33a90 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f returned and no
33aa0 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a data is read..*
33ab0 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74 * ^The size of t
33ac0 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e he blob (and hen
33ad0 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 ce the maximum v
33ae0 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 alue of N+iOffse
33af0 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 t).** can be det
33b00 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 ermined using th
33b10 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
33b20 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 bytes()] interfa
33b30 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 ce..**.** ^An at
33b40 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 tempt to read fr
33b50 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 om an expired [B
33b60 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c LOB handle] fail
33b70 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 s with an.** err
33b80 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 or code of [SQLI
33b90 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a TE_ABORT]..**.**
33ba0 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 ^(On success, s
33bb0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 qlite3_blob_read
33bc0 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 () returns SQLIT
33bd0 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 E_OK..** Otherwi
33be0 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f se, an [error co
33bf0 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e de] or an [exten
33c00 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 ded error code]
33c10 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a is returned.)^.*
33c20 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
33c30 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 e only works on
33c40 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 a [BLOB handle]
33c50 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 which has been c
33c60 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 reated.** by a p
33c70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 rior successful
33c80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
33c90 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e _blob_open()] an
33ca0 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a d which has not.
33cb0 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 ** been closed b
33cc0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f y [sqlite3_blob_
33cd0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 close()]. Passi
33ce0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 ng any other poi
33cf0 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 nter in.** to th
33d00 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c is routine resul
33d10 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 ts in undefined
33d20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 and probably und
33d30 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f esirable behavio
33d40 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 r..**.** See als
33d50 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 o: [sqlite3_blob
33d60 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e _write()]..*/.in
33d70 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 t sqlite3_blob_r
33d80 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ead(sqlite3_blob
33d90 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 *, void *Z, int
33da0 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 N, int iOffset)
33db0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
33dc0 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e F: Write Data In
33dd0 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d to A BLOB Increm
33de0 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 entally.**.** ^T
33df0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
33e00 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 used to write da
33e10 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 ta into an open
33e20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 [BLOB handle] fr
33e30 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 om a.** caller-s
33e40 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 upplied buffer.
33e50 5e 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 ^N bytes of data
33e60 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d are copied from
33e70 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a the buffer Z.**
33e80 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 into the open B
33e90 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 LOB, starting at
33ea0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e offset iOffset.
33eb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b .**.** ^If the [
33ec0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 BLOB handle] pas
33ed0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
33ee0 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f argument was no
33ef0 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 t opened for.**
33f00 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 writing (the fla
33f10 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 gs parameter to
33f20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
33f30 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c en()] was zero),
33f40 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f .** this functio
33f50 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 n returns [SQLIT
33f60 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a E_READONLY]..**.
33f70 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
33f80 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 n may only modif
33f90 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f y the contents o
33fa0 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 f the BLOB; it i
33fb0 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c s.** not possibl
33fc0 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 e to increase th
33fd0 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 e size of a BLOB
33fe0 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e using this API.
33ff0 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 .** ^If offset i
34000 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 Offset is less t
34010 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d han N bytes from
34020 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
34030 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 BLOB,.** [SQLITE
34040 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 _ERROR] is retur
34050 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 ned and no data
34060 69 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 is written. ^If
34070 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 N is.** less th
34080 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f an zero [SQLITE_
34090 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e ERROR] is return
340a0 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 ed and no data i
340b0 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 s written..** Th
340c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c e size of the BL
340d0 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 OB (and hence th
340e0 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 e maximum value
340f0 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a of N+iOffset).**
34100 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e can be determin
34110 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 ed using the [sq
34120 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 lite3_blob_bytes
34130 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
34140 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 *.** ^An attempt
34150 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 to write to an
34160 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 expired [BLOB ha
34170 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 ndle] fails with
34180 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 an.** error cod
34190 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f e of [SQLITE_ABO
341a0 52 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f RT]. ^Writes to
341b0 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f the BLOB that o
341c0 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 ccurred.** befor
341d0 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 e the [BLOB hand
341e0 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 le] expired are
341f0 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 not rolled back
34200 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 by the.** expira
34210 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 tion of the hand
34220 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f le, though of co
34230 75 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 urse those chang
34240 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 es might.** have
34250 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 been overwritte
34260 6e 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 n by the stateme
34270 6e 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20 nt that expired
34280 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a the BLOB handle.
34290 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 ** or by other i
342a0 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 ndependent state
342b0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f ments..**.** ^(O
342c0 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 n success, sqlit
342d0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 e3_blob_write()
342e0 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f returns SQLITE_O
342f0 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c K..** Otherwise,
34300 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 an [error code
34310 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 ] or an [extende
34320 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 d error code] is
34330 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a returned.)^.**.
34340 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
34350 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 only works on a
34360 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 [BLOB handle] wh
34370 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 ich has been cre
34380 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 ated.** by a pri
34390 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 or successful ca
343a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ll to [sqlite3_b
343b0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 lob_open()] and
343c0 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a which has not.**
343d0 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 been closed by
343e0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c [sqlite3_blob_cl
343f0 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 ose()]. Passing
34400 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 any other point
34410 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 er in.** to this
34420 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 routine results
34430 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e in undefined an
34440 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 d probably undes
34450 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e irable behavior.
34460 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
34470 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 [sqlite3_blob_r
34480 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 ead()]..*/.int s
34490 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 qlite3_blob_writ
344a0 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a e(sqlite3_blob *
344b0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c , const void *z,
344c0 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 int n, int iOff
344d0 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 set);../*.** CAP
344e0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 I3REF: Virtual F
344f0 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 ile System Objec
34500 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 ts.**.** A virtu
34510 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 al filesystem (V
34520 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 FS) is an [sqlit
34530 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a e3_vfs] object.*
34540 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 * that SQLite us
34550 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a es to interact.*
34560 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 * with the under
34570 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 lying operating
34580 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 system. Most SQ
34590 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 Lite builds come
345a0 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c with a.** singl
345b0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 e default VFS th
345c0 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 at is appropriat
345d0 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 e for the host c
345e0 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 omputer..** New
345f0 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 VFSes can be reg
34600 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 istered and exis
34610 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 ting VFSes can b
34620 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a e unregistered..
34630 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** The following
34640 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
34650 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 provided..**.**
34660 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 ^The sqlite3_vfs
34670 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 _find() interfac
34680 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
34690 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 ter to a VFS giv
346a0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 en its name..**
346b0 5e 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 ^Names are case
346c0 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e sensitive..** ^N
346d0 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 ames are zero-te
346e0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
346f0 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 trings..** ^If t
34700 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 here is no match
34710 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 , a NULL pointer
34720 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
34730 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 ^If zVfsName is
34740 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 NULL then the d
34750 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 efault VFS is re
34760 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e turned..**.** ^N
34770 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 ew VFSes are reg
34780 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c istered with sql
34790 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
347a0 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 r()..** ^Each ne
347b0 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 w VFS becomes th
347c0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 e default VFS if
347d0 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c the makeDflt fl
347e0 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 ag is set..** ^T
347f0 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 he same VFS can
34800 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 be registered mu
34810 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 ltiple times wit
34820 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 hout injury..**
34830 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 ^To make an exis
34840 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 ting VFS into th
34850 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 e default VFS, r
34860 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e egister it again
34870 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b .** with the mak
34880 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 eDflt flag set.
34890 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e If two differen
348a0 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 t VFSes with the
348b0 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 .** same name ar
348c0 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 e registered, th
348d0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
348e0 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a defined. If a.*
348f0 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 * VFS is registe
34900 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 red with a name
34910 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 that is NULL or
34920 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
34930 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 .** then the beh
34940 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
34950 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 ed..**.** ^Unreg
34960 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 ister a VFS with
34970 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
34980 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e _unregister() in
34990 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 terface..** ^(If
349a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 the default VFS
349b0 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 is unregistered
349c0 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 , another VFS is
349d0 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 chosen as.** th
349e0 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 e default. The
349f0 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e choice for the n
34a00 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 ew VFS is arbitr
34a10 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 ary.)^.*/.sqlite
34a20 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 3_vfs *sqlite3_v
34a30 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 fs_find(const ch
34a40 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 ar *zVfsName);.i
34a50 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 nt sqlite3_vfs_r
34a60 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f egister(sqlite3_
34a70 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 vfs*, int makeDf
34a80 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 lt);.int sqlite3
34a90 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 _vfs_unregister(
34aa0 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a sqlite3_vfs*);..
34ab0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
34ac0 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 Mutexes.**.** Th
34ad0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 e SQLite core us
34ae0 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 es these routine
34af0 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 s for thread.**
34b00 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e synchronization.
34b10 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 Though they are
34b20 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e intended for in
34b30 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 ternal.** use by
34b40 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 SQLite, code th
34b50 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 at links against
34b60 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 SQLite is.** pe
34b70 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 rmitted to use a
34b80 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
34b90 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ines..**.** The
34ba0 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f SQLite source co
34bb0 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 de contains mult
34bc0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 iple implementat
34bd0 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 ions.** of these
34be0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e mutex routines.
34bf0 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 An appropriate
34c00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
34c10 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 ** is selected a
34c20 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 utomatically at
34c30 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e compile-time. ^
34c40 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a (The following.*
34c50 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
34c60 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 s are available
34c70 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f in the SQLite co
34c80 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a re:.**.** <ul>.*
34c90 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f * <li> SQLITE_
34ca0 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 MUTEX_OS2.** <li
34cb0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 > SQLITE_MUTEX
34cc0 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e _PTHREAD.** <li>
34cd0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f SQLITE_MUTEX_
34ce0 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 W32.** <li> SQ
34cf0 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a LITE_MUTEX_NOOP.
34d00 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a ** </ul>)^.**.**
34d10 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 ^The SQLITE_MUT
34d20 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e EX_NOOP implemen
34d30 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 tation is a set
34d40 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 of routines.** t
34d50 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c hat does no real
34d60 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 locking and is
34d70 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 appropriate for
34d80 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 use in.** a sing
34d90 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c le-threaded appl
34da0 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 ication. ^The S
34db0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c QLITE_MUTEX_OS2,
34dc0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 .** SQLITE_MUTEX
34dd0 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 _PTHREAD, and SQ
34de0 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 LITE_MUTEX_W32 i
34df0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a mplementations.*
34e00 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 * are appropriat
34e10 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f e for use on OS/
34e20 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 2, Unix, and Win
34e30 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 dows..**.** ^(If
34e40 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
34e50 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c led with the SQL
34e60 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 ITE_MUTEX_APPDEF
34e70 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a preprocessor.**
34e80 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 macro defined (
34e90 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d with "-DSQLITE_M
34ea0 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c UTEX_APPDEF=1"),
34eb0 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a then no mutex.*
34ec0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
34ed0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 is included wit
34ee0 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 h the library. I
34ef0 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a n this case the.
34f00 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d ** application m
34f10 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 ust supply a cus
34f20 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d tom mutex implem
34f30 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 entation using t
34f40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f he.** [SQLITE_CO
34f50 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 NFIG_MUTEX] opti
34f60 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 on of the sqlite
34f70 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 3_config() funct
34f80 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 ion.** before ca
34f90 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e lling sqlite3_in
34fa0 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e itialize() or an
34fb0 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 y other public s
34fc0 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 qlite3_.** funct
34fd0 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 ion that calls s
34fe0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
34ff0 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 e().)^.**.** ^Th
35000 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
35010 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 alloc() routine
35020 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a allocates a new.
35030 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 ** mutex and ret
35040 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
35050 6f 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74 o it. ^If it ret
35060 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 urns NULL.** tha
35070 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d t means that a m
35080 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 utex could not b
35090 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 e allocated. ^S
350a0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e QLite.** will un
350b0 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 wind its stack a
350c0 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 nd return an err
350d0 6f 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d or. ^(The argum
350e0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
350f0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 3_mutex_alloc()
35100 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 is one of these
35110 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
35120 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
35130 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
35140 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e TEX_FAST.** <li>
35150 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 SQLITE_MUTEX_R
35160 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e ECURSIVE.** <li>
35170 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
35180 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 TATIC_MASTER.**
35190 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
351a0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a EX_STATIC_MEM.**
351b0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
351c0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a TEX_STATIC_MEM2.
351d0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
351e0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e MUTEX_STATIC_PRN
351f0 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 G.** <li> SQLIT
35200 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c E_MUTEX_STATIC_L
35210 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 RU.** <li> SQLI
35220 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
35230 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a LRU2.** </ul>)^.
35240 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
35250 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 two constants (
35260 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
35270 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 T and SQLITE_MUT
35280 45 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a EX_RECURSIVE).**
35290 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d cause sqlite3_m
352a0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 utex_alloc() to
352b0 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 create.** a new
352c0 6d 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 mutex. ^The new
352d0 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 mutex is recurs
352e0 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f ive when SQLITE_
352f0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a MUTEX_RECURSIVE.
35300 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e ** is used but n
35310 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 ot necessarily s
35320 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 o when SQLITE_MU
35330 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 TEX_FAST is used
35340 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 ..** The mutex i
35350 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f mplementation do
35360 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d es not need to m
35370 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f ake a distinctio
35380 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c n.** between SQL
35390 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
353a0 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d IVE and SQLITE_M
353b0 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 UTEX_FAST if it
353c0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 does.** not want
353d0 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 to. ^SQLite wi
353e0 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 ll only request
353f0 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 a recursive mute
35400 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 x in.** cases wh
35410 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 ere it really ne
35420 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 eds one. ^If a
35430 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 faster non-recur
35440 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d sive mutex.** im
35450 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
35460 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 available on the
35470 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 host platform,
35480 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 the mutex subsys
35490 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 tem.** might ret
354a0 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 urn such a mutex
354b0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 in response to
354c0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
354d0 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 T..**.** ^The ot
354e0 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 her allowed para
354f0 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 meters to sqlite
35500 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 3_mutex_alloc()
35510 28 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a (anything other.
35520 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d ** than SQLITE_M
35530 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 UTEX_FAST and SQ
35540 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
35550 53 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72 SIVE) each retur
35560 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 n.** a pointer t
35570 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 o a static preex
35580 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e isting mutex. ^
35590 53 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78 Six static mutex
355a0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 es are.** used b
355b0 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 y the current ve
355c0 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e rsion of SQLite.
355d0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
355e0 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d s of SQLite.** m
355f0 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 ay add additiona
35600 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 l static mutexes
35610 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 . Static mutexe
35620 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e s are for intern
35630 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c al.** use by SQL
35640 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 ite only. Appli
35650 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 cations that use
35660 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 SQLite mutexes
35670 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e should.** use on
35680 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d ly the dynamic m
35690 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 utexes returned
356a0 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f by SQLITE_MUTEX_
356b0 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 FAST or.** SQLIT
356c0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 E_MUTEX_RECURSIV
356d0 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 E..**.** ^Note t
356e0 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 hat if one of th
356f0 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 e dynamic mutex
35700 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 parameters (SQLI
35710 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a TE_MUTEX_FAST.**
35720 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 or SQLITE_MUTEX
35730 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 _RECURSIVE) is u
35740 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 sed then sqlite3
35750 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a _mutex_alloc().*
35760 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 * returns a diff
35770 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 erent mutex on e
35780 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 very call. ^But
35790 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a for the static.
357a0 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 ** mutex types,
357b0 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 the same mutex i
357c0 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 s returned on ev
357d0 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 ery call that ha
357e0 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 s.** the same ty
357f0 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a pe number..**.**
35800 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 ^The sqlite3_mu
35810 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 tex_free() routi
35820 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ne deallocates a
35830 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 previously.** a
35840 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 llocated dynamic
35850 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 mutex. ^SQLite
35860 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 is careful to d
35870 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a eallocate every.
35880 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 ** dynamic mutex
35890 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 that it allocat
358a0 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 es. The dynamic
358b0 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f mutexes must no
358c0 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 t be in.** use w
358d0 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 hen they are dea
358e0 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d llocated. Attem
358f0 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 pting to dealloc
35900 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 ate a static.**
35910 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e mutex results in
35920 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
35930 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 ior. ^SQLite ne
35940 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a ver deallocates.
35950 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 ** a static mute
35960 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 x..**.** ^The sq
35970 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
35980 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f r() and sqlite3_
35990 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 mutex_try() rout
359a0 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 ines attempt.**
359b0 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 to enter a mutex
359c0 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 . ^If another t
359d0 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 hread is already
359e0 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 within the mute
359f0 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 x,.** sqlite3_mu
35a00 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c tex_enter() will
35a10 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 block and sqlit
35a20 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 e3_mutex_try() w
35a30 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 ill return.** SQ
35a40 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 LITE_BUSY. ^The
35a50 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
35a60 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ry() interface r
35a70 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
35a80 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 K].** upon succe
35a90 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 ssful entry. ^(
35aa0 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20 Mutexes created
35ab0 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f using.** SQLITE_
35ac0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 MUTEX_RECURSIVE
35ad0 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d can be entered m
35ae0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 ultiple times by
35af0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
35b00 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73 ..** In such cas
35b10 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 es the,.** mutex
35b20 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 must be exited
35b30 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 an equal number
35b40 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 of times before
35b50 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a another thread.*
35b60 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 * can enter.)^
35b70 5e 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 ^(If the same th
35b80 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e read tries to en
35b90 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a ter any other.**
35ba0 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d kind of mutex m
35bb0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 ore than once, t
35bc0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
35bd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c ndefined..** SQL
35be0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 ite will never e
35bf0 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 xhibit.** such b
35c00 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f ehavior in its o
35c10 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 wn use of mutexe
35c20 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d s.)^.**.** ^(Som
35c30 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 e systems (for e
35c40 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 xample, Windows
35c50 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 95) do not suppo
35c60 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e rt the operation
35c70 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 .** implemented
35c80 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 by sqlite3_mutex
35c90 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 _try(). On thos
35ca0 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 e systems, sqlit
35cb0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a e3_mutex_try().*
35cc0 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 * will always re
35cd0 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 turn SQLITE_BUSY
35ce0 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f . The SQLite co
35cf0 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 re only ever use
35d00 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 s.** sqlite3_mut
35d10 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f ex_try() as an o
35d20 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 ptimization so t
35d30 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c his is acceptabl
35d40 65 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a e behavior.)^.**
35d50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
35d60 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 _mutex_leave() r
35d70 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d outine exits a m
35d80 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a utex that was.**
35d90 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 previously ente
35da0 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 red by the same
35db0 74 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20 thread. ^(The
35dc0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 behavior.** is u
35dd0 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 ndefined if the
35de0 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 mutex is not cur
35df0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 rently entered b
35e00 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 y the.** calling
35e10 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f thread or is no
35e20 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f t currently allo
35e30 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 cated. SQLite w
35e40 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 ill.** never do
35e50 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 either.)^.**.**
35e60 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 ^If the argument
35e70 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
35e80 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 x_enter(), sqlit
35e90 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 e3_mutex_try(),
35ea0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 or.** sqlite3_mu
35eb0 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 tex_leave() is a
35ec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 NULL pointer, t
35ed0 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f hen all three ro
35ee0 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 utines.** behave
35ef0 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a as no-ops..**.*
35f00 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
35f10 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
35f20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
35f30 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d mutex_notheld()]
35f40 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 ..*/.sqlite3_mut
35f50 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 ex *sqlite3_mute
35f60 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f x_alloc(int);.vo
35f70 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 id sqlite3_mutex
35f80 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 _free(sqlite3_mu
35f90 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 tex*);.void sqli
35fa0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 te3_mutex_enter(
35fb0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
35fc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 .int sqlite3_mut
35fd0 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d ex_try(sqlite3_m
35fe0 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c utex*);.void sql
35ff0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
36000 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 (sqlite3_mutex*)
36010 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
36020 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 F: Mutex Methods
36030 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 Object.** EXPER
36040 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e IMENTAL.**.** An
36050 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
36060 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 s structure defi
36070 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 nes the low-leve
36080 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 l routines.** us
36090 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 ed to allocate a
360a0 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a nd use mutexes..
360b0 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 **.** Usually, t
360c0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 he default mutex
360d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
360e0 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c provided by SQL
360f0 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 ite are.** suffi
36100 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 cient, however t
36110 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 he user has the
36120 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 option of substi
36130 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a tuting a custom.
36140 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
36150 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 n for specialize
36160 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 d deployments or
36170 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 systems for whi
36180 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 ch SQLite.** doe
36190 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 s not provide a
361a0 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 suitable impleme
361b0 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 ntation. In this
361c0 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a case, the user.
361d0 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 ** creates and p
361e0 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 opulates an inst
361f0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 ance of this str
36200 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a ucture to pass.*
36210 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e * to sqlite3_con
36220 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 fig() along with
36230 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
36240 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f FIG_MUTEX] optio
36250 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c n..** Additional
36260 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 ly, an instance
36270 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
36280 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 e can be used as
36290 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 an.** output va
362a0 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 riable when quer
362b0 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 ying the system
362c0 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 for the current
362d0 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 mutex.** impleme
362e0 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 ntation, using t
362f0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
36300 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 G_GETMUTEX] opti
36310 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 on..**.** ^The x
36320 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 MutexInit method
36330 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 defined by this
36340 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e structure is in
36350 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 voked as.** part
36360 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 of system initi
36370 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 alization by the
36380 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
36390 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a ize() function..
363a0 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e ** ^The xMutexIn
363b0 69 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 it routine is ca
363c0 6c 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78 lle by SQLite ex
363d0 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 actly once for e
363e0 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 ach.** effective
363f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
36400 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 3_initialize()].
36410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 .**.** ^The xMut
36420 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 exEnd method def
36430 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 ined by this str
36440 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 ucture is invoke
36450 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 d as.** part of
36460 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 system shutdown
36470 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
36480 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 hutdown() functi
36490 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 on. The.** imple
364a0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 mentation of thi
364b0 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 s method is expe
364c0 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 cted to release
364d0 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a all outstanding.
364e0 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 ** resources obt
364f0 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 ained by the mut
36500 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 ex methods imple
36510 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 mentation, espec
36520 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f ially.** those o
36530 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 btained by the x
36540 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 MutexInit method
36550 2e 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e . ^The xMutexEn
36560 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 d().** interface
36570 20 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 is invoked exac
36580 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 tly once for eac
36590 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 h call to [sqlit
365a0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a e3_shutdown()]..
365b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 **.** ^(The rema
365c0 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 ining seven meth
365d0 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 ods defined by t
365e0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78 his structure (x
365f0 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 MutexAlloc,.** x
36600 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 MutexFree, xMute
36610 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 xEnter, xMutexTr
36620 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 y, xMutexLeave,
36630 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a xMutexHeld and.*
36640 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 * xMutexNotheld)
36650 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 implement the f
36660 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 ollowing interfa
36670 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c ces (respectivel
36680 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a y):.**.** <ul>.*
36690 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 * <li> [sqlit
366a0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
366b0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
366c0 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
366d0 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a x_free()] </li>.
366e0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
366f0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 te3_mutex_enter(
36700 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
36710 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
36720 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a ex_try()] </li>.
36730 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
36740 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 te3_mutex_leave(
36750 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
36760 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
36770 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e ex_held()] </li>
36780 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
36790 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 ite3_mutex_nothe
367a0 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c ld()] </li>.** <
367b0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 /ul>)^.**.** The
367c0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 only difference
367d0 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62 is that the pub
367e0 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 lic sqlite3_XXX
367f0 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 functions enumer
36800 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 ated.** above si
36810 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e lently ignore an
36820 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 y invocations th
36830 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 at pass a NULL p
36840 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a ointer instead.*
36850 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 * of a valid mut
36860 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 ex handle. The i
36870 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
36880 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 f the methods de
36890 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 fined.** by this
368a0 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e structure are n
368b0 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 ot required to h
368c0 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c andle this case,
368d0 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 the results.**
368e0 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c of passing a NUL
368f0 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 L pointer instea
36900 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 d of a valid mut
36910 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e ex handle are un
36920 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e defined.** (i.e.
36930 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c it is acceptabl
36940 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 e to provide an
36950 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 implementation t
36960 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 hat segfaults if
36970 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 .** it is passed
36980 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 a NULL pointer)
36990 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 ..**.** The xMut
369a0 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 exInit() method
369b0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
369c0 66 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65 fe. ^It must be
369d0 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 harmless to.**
369e0 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 invoke xMutexIni
369f0 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 t() mutiple time
36a00 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d s within the sam
36a10 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 e process and wi
36a20 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 thout.** interve
36a30 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d ning calls to xM
36a40 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f utexEnd(). Seco
36a50 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
36a60 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d t calls to.** xM
36a70 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 utexInit() must
36a80 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a be no-ops..**.**
36a90 20 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d ^xMutexInit() m
36aa0 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 ust not use SQLi
36ab0 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 te memory alloca
36ac0 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d tion ([sqlite3_m
36ad0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 alloc()].** and
36ae0 69 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e its associates).
36af0 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d ^Similarly, xM
36b00 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 utexAlloc() must
36b10 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 not use SQLite
36b20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
36b30 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 tion for a stati
36b40 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 c mutex. ^Howev
36b50 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 er xMutexAlloc()
36b60 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a may use SQLite.
36b70 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
36b80 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 tion for a fast
36b90 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 or recursive mut
36ba0 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 ex..**.** ^SQLit
36bb0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 e will invoke th
36bc0 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 e xMutexEnd() me
36bd0 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 thod when [sqlit
36be0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 e3_shutdown()] i
36bf0 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 s.** called, but
36c00 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69 only if the pri
36c10 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 or call to xMute
36c20 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53 xInit returned S
36c30 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 QLITE_OK..** If
36c40 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73 xMutexInit fails
36c50 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20 in any way, it
36c60 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63 is expected to c
36c70 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74 lean up after it
36c80 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f self.** prior to
36c90 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 returning..*/.t
36ca0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
36cb0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
36cc0 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 ods sqlite3_mute
36cd0 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 x_methods;.struc
36ce0 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f t sqlite3_mutex_
36cf0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 methods {. int
36d00 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f (*xMutexInit)(vo
36d10 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 id);. int (*xMu
36d20 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 texEnd)(void);.
36d30 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a sqlite3_mutex *
36d40 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 (*xMutexAlloc)(i
36d50 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d nt);. void (*xM
36d60 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 utexFree)(sqlite
36d70 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 3_mutex *);. vo
36d80 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 id (*xMutexEnter
36d90 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 )(sqlite3_mutex
36da0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 *);. int (*xMut
36db0 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d exTry)(sqlite3_m
36dc0 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 utex *);. void
36dd0 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 (*xMutexLeave)(s
36de0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b qlite3_mutex *);
36df0 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 . int (*xMutexH
36e00 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 eld)(sqlite3_mut
36e10 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ex *);. int (*x
36e20 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 MutexNotheld)(sq
36e30 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a lite3_mutex *);.
36e40 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
36e50 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 EF: Mutex Verifi
36e60 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a cation Routines.
36e70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
36e80 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 3_mutex_held() a
36e90 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 nd sqlite3_mutex
36ea0 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 _notheld() routi
36eb0 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e nes.** are inten
36ec0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 ded for use insi
36ed0 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 de assert() stat
36ee0 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 ements. ^The SQ
36ef0 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 Lite core.** nev
36f00 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f er uses these ro
36f10 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e utines except in
36f20 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 side an assert()
36f30 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e and application
36f40 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 s.** are advised
36f50 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c to follow the l
36f60 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e ead of the core.
36f70 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f ^The SQLite co
36f80 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 re only.** provi
36f90 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 des implementati
36fa0 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f ons for these ro
36fb0 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 utines when it i
36fc0 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 s compiled.** wi
36fd0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 th the SQLITE_DE
36fe0 42 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 BUG flag. ^Exte
36ff0 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 rnal mutex imple
37000 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 mentations.** ar
37010 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 e only required
37020 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 to provide these
37030 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c routines if SQL
37040 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 ITE_DEBUG is.**
37050 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e defined and if N
37060 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 DEBUG is not def
37070 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
37080 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 se routines shou
37090 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 ld return true i
370a0 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 f the mutex in t
370b0 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a heir argument.**
370c0 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 is held or not
370d0 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 held, respective
370e0 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 ly, by the calli
370f0 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a ng thread..**.**
37100 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 ^The implementa
37110 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 tion is not requ
37120 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 ired to provided
37130 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 versions of the
37140 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 se.** routines t
37150 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 hat actually wor
37160 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d k. If the implem
37170 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f entation does no
37180 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e t provide workin
37190 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 g.** versions of
371a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c these routines,
371b0 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 it should at le
371c0 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 ast provide stub
371d0 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a s that always.**
371e0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 return true so
371f0 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f that one does no
37200 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 t get spurious a
37210 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 ssertion failure
37220 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 s..**.** ^If the
37230 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
37240 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
37250 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ) is a NULL poin
37260 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ter then.** the
37270 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 routine should r
37280 65 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20 eturn 1. This
37290 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e seems counter-in
372a0 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a tuitive since.**
372b0 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 clearly the mut
372c0 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c ex cannot be hel
372d0 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 d if it does not
372e0 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 exist. But the
372f0 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 .** the reason t
37300 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f he mutex does no
37310 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 t exist is becau
37320 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 se the build is
37330 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 not.** using mut
37340 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f exes. And we do
37350 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 not want the as
37360 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e sert() containin
37370 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f g the.** call to
37380 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 sqlite3_mutex_h
37390 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 eld() to fail, s
373a0 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 o a non-zero ret
373b0 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 urn is.** the ap
373c0 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 propriate thing
373d0 74 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c to do. ^The sql
373e0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 ite3_mutex_nothe
373f0 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 ld().** interfac
37400 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 e should also re
37410 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 turn 1 when give
37420 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 n a NULL pointer
37430 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 ..*/.#ifndef NDE
37440 42 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f BUG.int sqlite3_
37450 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 mutex_held(sqlit
37460 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 e3_mutex*);.int
37470 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f sqlite3_mutex_no
37480 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 theld(sqlite3_mu
37490 74 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f tex*);.#endif../
374a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
374b0 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a utex Types.**.**
374c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 The [sqlite3_mu
374d0 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 tex_alloc()] int
374e0 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 erface takes a s
374f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a ingle argument.*
37500 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f * which is one o
37510 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 f these integer
37520 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a constants..**.**
37530 20 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 The set of stat
37540 69 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 ic mutexes may c
37550 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 hange from one S
37560 51 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f QLite release to
37570 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 the.** next. A
37580 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
37590 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75 override the bu
375a0 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 ilt-in mutex log
375b0 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 ic must be.** pr
375c0 65 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d epared to accomm
375d0 6f 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c odate additional
375e0 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e static mutexes.
375f0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
37600 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 TE_MUTEX_FAST
37610 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 0.#def
37620 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
37630 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 _RECURSIVE
37640 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
37650 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
37660 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 MASTER 2.#def
37670 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
37680 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 _STATIC_MEM
37690 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 3 /* sqlite3_
376a0 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 malloc() */.#def
376b0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
376c0 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 _STATIC_MEM2
376d0 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 4 /* NOT USED
376e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
376f0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
37700 4f 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 OPEN 4 /*
37710 73 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e sqlite3BtreeOpen
37720 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
37730 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
37740 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f C_PRNG 5 /
37750 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d * sqlite3_random
37760 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
37770 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
37780 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f C_LRU 6 /
37790 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 * lru page list
377a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
377b0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c E_MUTEX_STATIC_L
377c0 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c RU2 7 /* l
377d0 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a ru page list */.
377e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
377f0 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 Retrieve the mu
37800 74 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 tex for a databa
37810 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
37820 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 .** ^This interf
37830 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
37840 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 inter the [sqlit
37850 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 e3_mutex] object
37860 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c that .** serial
37870 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 izes access to t
37880 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
37890 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 nection] given i
378a0 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a n the argument.*
378b0 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 * when the [thre
378c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 ading mode] is S
378d0 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 49 erialized..** ^I
378e0 66 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 f the [threading
378f0 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 mode] is Single
37900 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 -thread or Multi
37910 2d 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 -thread then thi
37920 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 s.** routine ret
37930 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
37940 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f ter..*/.sqlite3_
37950 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 mutex *sqlite3_d
37960 62 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a b_mutex(sqlite3*
37970 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
37980 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f EF: Low-Level Co
37990 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 ntrol Of Databas
379a0 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 e Files.**.** ^T
379b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
379c0 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 _control()] inte
379d0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 rface makes a di
379e0 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 rect call to the
379f0 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c .** xFileControl
37a00 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 method for the
37a10 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
37a20 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f ods] object asso
37a30 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 ciated.** with a
37a40 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 particular data
37a50 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 base identified
37a60 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 by the second ar
37a70 67 75 6d 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a 20 gument. ^The.**
37a80 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
37a90 62 61 73 65 20 22 6d 61 69 6e 22 20 66 6f 72 20 base "main" for
37aa0 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 the main databas
37ab0 65 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72 20 e or "temp" for
37ac0 74 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74 61 the.** TEMP data
37ad0 62 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61 6d base, or the nam
37ae0 65 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61 e that appears a
37af0 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 fter the AS keyw
37b00 6f 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 ord for.** datab
37b10 61 73 65 73 20 74 68 61 74 20 61 72 65 20 61 64 ases that are ad
37b20 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 41 ded using the [A
37b30 54 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d 61 TTACH] SQL comma
37b40 6e 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20 70 nd..** ^A NULL p
37b50 6f 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75 73 ointer can be us
37b60 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 ed in place of "
37b70 6d 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20 74 main" to refer t
37b80 6f 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64 61 o the.** main da
37b90 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 tabase file..**
37ba0 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 ^The third and f
37bb0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 ourth parameters
37bc0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
37bd0 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 .** are passed d
37be0 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 irectly through
37bf0 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e to the second an
37c00 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 d third paramete
37c10 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 rs of.** the xFi
37c20 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
37c30 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 . ^The return v
37c40 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c alue of the xFil
37c50 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 eControl.** meth
37c60 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 od becomes the r
37c70 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
37c80 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a his routine..**.
37c90 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e ** ^If the secon
37ca0 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 d parameter (zDb
37cb0 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d Name) does not m
37cc0 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 atch the name of
37cd0 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 any.** open dat
37ce0 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e abase file, then
37cf0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 SQLITE_ERROR is
37d00 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 69 returned. ^Thi
37d10 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 s error.** code
37d20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 is not remembere
37d30 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 d and will not b
37d40 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 e recalled by [s
37d50 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
37d60 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
37d70 5f 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68 65 _errmsg()]. The
37d80 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c underlying xFil
37d90 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
37da0 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 might.** also re
37db0 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f turn SQLITE_ERRO
37dc0 52 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f 20 R. There is no
37dd0 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69 way to distingui
37de0 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e sh between.** an
37df0 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 incorrect zDbNa
37e00 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 me and an SQLITE
37e10 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72 _ERROR return fr
37e20 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e om the underlyin
37e30 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f g.** xFileContro
37e40 6c 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 l method..**.**
37e50 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 See also: [SQLIT
37e60 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
37e70 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 E].*/.int sqlite
37e80 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 3_file_control(s
37e90 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 qlite3*, const c
37ea0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e har *zDbName, in
37eb0 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f t op, void*);../
37ec0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
37ed0 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 esting Interface
37ee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
37ef0 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c te3_test_control
37f00 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
37f10 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74 used to read out
37f20 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 internal.** sta
37f30 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 te of SQLite and
37f40 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 to inject fault
37f50 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f s into SQLite fo
37f60 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 r testing.** pur
37f70 70 6f 73 65 73 2e 20 20 5e 54 68 65 20 66 69 72 poses. ^The fir
37f80 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
37f90 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 an operation cod
37fa0 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 e that determine
37fb0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c s.** the number,
37fc0 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 meaning, and op
37fd0 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 eration of all s
37fe0 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 ubsequent parame
37ff0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ters..**.** This
38000 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
38010 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 t for use by app
38020 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 lications. It e
38030 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 xists solely.**
38040 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 for verifying th
38050 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 e correct operat
38060 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ion of the SQLit
38070 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 e library. Depe
38080 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 nding.** on how
38090 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
380a0 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 ry is compiled,
380b0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d this interface m
380c0 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a ight not exist..
380d0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c **.** The detail
380e0 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 s of the operati
380f0 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 on codes, their
38100 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 meanings, the pa
38110 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 rameters.** they
38120 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 take, and what
38130 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 they do are all
38140 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
38150 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 e without notice
38160 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 ..** Unlike most
38170 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 of the SQLite A
38180 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f PI, this functio
38190 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 n is not guarant
381a0 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 eed to.** operat
381b0 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 e consistently f
381c0 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 rom one release
381d0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a to the next..*/.
381e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 int sqlite3_test
381f0 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c _control(int op,
38200 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
38210 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 PI3REF: Testing
38220 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 Interface Operat
38230 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 ion Codes.**.**
38240 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
38250 61 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 are the valid op
38260 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 eration code par
38270 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 ameters used.**
38280 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
38290 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
382a0 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 3_test_control()
382b0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 ]..**.** These p
382c0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 arameters and th
382d0 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 eir meanings are
382e0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
382f0 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f ge.** without no
38300 74 69 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c tice. These val
38310 75 65 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 ues are for test
38320 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c ing purposes onl
38330 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f y..** Applicatio
38340 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 ns should not us
38350 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 e any of these p
38360 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 arameters or the
38370 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 .** [sqlite3_tes
38380 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 t_control()] int
38390 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 erface..*/.#defi
383a0 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
383b0 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 20 RL_PRNG_SAVE
383c0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 5.#d
383d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
383e0 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f TCTRL_PRNG_RESTO
383f0 52 45 20 20 20 20 20 20 20 20 20 20 20 20 20 36 RE 6
38400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
38410 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 TESTCTRL_PRNG_RE
38420 53 45 54 20 20 20 20 20 20 20 20 20 20 20 20 20 SET
38430 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
38440 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 56 TE_TESTCTRL_BITV
38450 45 43 5f 54 45 53 54 20 20 20 20 20 20 20 20 20 EC_TEST
38460 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 8.#define S
38470 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 QLITE_TESTCTRL_F
38480 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 AULT_INSTALL
38490 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
384a0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 e SQLITE_TESTCTR
384b0 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f L_BENIGN_MALLOC_
384c0 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 65 HOOKS 10.#de
384d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
384e0 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 CTRL_PENDING_BYT
384f0 45 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a E 11.
38500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
38510 45 53 54 43 54 52 4c 5f 41 53 53 45 52 54 20 20 ESTCTRL_ASSERT
38520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
38530 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 12.#define SQLIT
38540 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 41 59 E_TESTCTRL_ALWAY
38550 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 S
38560 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 13.#define SQ
38570 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 52 45 LITE_TESTCTRL_RE
38580 53 45 52 56 45 20 20 20 20 20 20 20 20 20 20 20 SERVE
38590 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 14../*.**
385a0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74 65 CAPI3REF: SQLite
385b0 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73 0a Runtime Status.
385c0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
385d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 **.** ^This inte
385e0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
385f0 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d retrieve runtim
38600 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 e status informa
38610 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68 tion.** about th
38620 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f 66 e preformance of
38630 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70 74 SQLite, and opt
38640 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65 74 ionally to reset
38650 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67 68 various.** high
38660 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 5e 54 water marks. ^T
38670 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
38680 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
38690 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 code for.** the
386a0 73 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 74 specific paramet
386b0 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 20 er to measure.
386c0 5e 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65 ^Recognized inte
386d0 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 ger codes.** are
386e0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 51 of the form [SQ
386f0 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f LITE_STATUS_MEMO
38700 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 45 RY_USED | SQLITE
38710 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a _STATUS_...]..**
38720 20 5e 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 ^The current va
38730 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d lue of the param
38740 65 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 eter is returned
38750 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e into *pCurrent.
38760 0a 2a 2a 20 5e 54 68 65 20 68 69 67 68 65 73 74 .** ^The highest
38770 20 72 65 63 6f 72 64 65 64 20 76 61 6c 75 65 20 recorded value
38780 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a is returned in *
38790 70 48 69 67 68 77 61 74 65 72 2e 20 20 5e 49 66 pHighwater. ^If
387a0 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61 the.** resetFla
387b0 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 g is true, then
387c0 74 68 65 20 68 69 67 68 65 73 74 20 72 65 63 6f the highest reco
387d0 72 64 20 76 61 6c 75 65 20 69 73 20 72 65 73 65 rd value is rese
387e0 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67 t after.** *pHig
387f0 68 77 61 74 65 72 20 69 73 20 77 72 69 74 74 65 hwater is writte
38800 6e 2e 20 20 5e 28 53 6f 6d 65 20 70 61 72 61 6d n. ^(Some param
38810 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 eters do not rec
38820 6f 72 64 20 74 68 65 20 68 69 67 68 65 73 74 0a ord the highest.
38830 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 ** value. For t
38840 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a hose parameters.
38850 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 ** nothing is wr
38860 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 itten into *pHig
38870 68 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 hwater and the r
38880 65 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f esetFlag is igno
38890 72 65 64 2e 29 5e 0a 2a 2a 20 5e 28 4f 74 68 65 red.)^.** ^(Othe
388a0 72 20 70 61 72 61 6d 65 74 65 72 73 20 72 65 63 r parameters rec
388b0 6f 72 64 20 6f 6e 6c 79 20 74 68 65 20 68 69 67 ord only the hig
388c0 68 77 61 74 65 72 20 6d 61 72 6b 20 61 6e 64 20 hwater mark and
388d0 6e 6f 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a not the current.
388e0 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 ** value. For t
388f0 68 65 73 65 20 6c 61 74 74 65 72 20 70 61 72 61 hese latter para
38900 6d 65 74 65 72 73 20 6e 6f 74 68 69 6e 67 20 69 meters nothing i
38910 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a s written into *
38920 70 43 75 72 72 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a pCurrent.)^.**.*
38930 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f