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 2c 20 73 71 6c 69 74 65 33 5f 73 rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 rovide the same
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 rary instead of
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 ^(Cautious.**
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 on to.** verify
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 he macros in.**
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 the header, and
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 is.** compiled
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 constant. The
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 DLL. ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 ON_NUMBER]. ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 ter to a string
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61 void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 on returns 0 or
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 compile time.
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 ed from the .**
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 (). .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74 ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 erating.** over
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 on string. ^If
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 pointer. ^The
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 tion at compile
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 time..**.** See
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 exes. When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 adsafe. When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d . Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 utexes incurs a
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d . But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 of SQLite that
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c E] flag. If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 tially disabled
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 using a call to
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 NFIG_MUTEX]. ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 e3_threadsafe()
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79 ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 at setting made
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 ] documentation
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 ORDS: {database
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 sqlite3". It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 * pointer as an
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 object. The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 estructor. Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 y_timeout()] to
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 name but three)
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 _uint64 are the
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 he sqlite_int64
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a lusive. ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 sqlite3_uint64
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 (__BORLANDC__).
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 _uint64;.#else.
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 nt64;../*.** If
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 compiling for a
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 int support,.**
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69 e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75 ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75 te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 rn SQLITE_OK if
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65 ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79 ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20 iated resources
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a object. ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 is called on a
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65 OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 n it returns.**
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55 lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72 ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 recated. It is
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 tibility and is
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 use a lot of C
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 interface runs
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 st.** argument.
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 ments. ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 ough to the 1st
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 ocation. ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 ipped. ^If the
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ning..**.** ^If
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ns SQLITE_ABORT
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 ult. ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e . ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 lback is a NULL
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 pointer. ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 ntry represents
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 comments, then
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 s are evaluated
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 insure that the
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c ** is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 specified by.**
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 ent text passed
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 into.** the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 sqlite3*,
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 *sql,
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 aluated */. int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 ar**), /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 void *,
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 1st argument to
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 callback */. ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 ar **errmsg
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 re */.);../*.**
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 SQLITE_ERROR
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 1 /* SQL
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 RNAL 2 /*
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 _PERM 3
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 ABORT 4
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 ne SQLITE_BUSY
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 5 /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 ED 6 /*
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ITE_NOMEM
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 7 /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 ONLY 8 /*
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 base */.#define
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 9 /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 tion terminated
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 SQLITE_IOERR
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 10 /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 TE_CORRUPT 1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 1 /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f TFOUND 12 /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 e or record not
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 SQLITE_FULL
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 13 /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 14 /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 ROTOCOL 15
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 protocol error
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 E_EMPTY 16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 17 /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 IG 18 /*
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 ITE_CONSTRAINT
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 19 /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 e to constraint
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 ATCH 20 /*
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 LITE_MISUSE
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 21 /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 ITE_NOLFS
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 22 /* Uses OS
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 _AUTH 23
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 AT 24 /*
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 se format error
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 E_RANGE 25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 TE_NOTADB 2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 6 /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 _ROW 100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 p() has another
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 101 /*
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 ORDS: {extended
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 s}.** KEYWORDS:
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 ** [SQLITE_OK |
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 result codes].
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 grained. They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 rs might like.
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 newer versions
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 es that provide
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 is using the.**
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 may expect the
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f * over time. So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ew result codes
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 nded. It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 R_READ
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 _SHORT_READ
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 WRITE
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 SYNC
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 R_FSYNC
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (5<<8)).#define
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 NCATE (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 T (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 K (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 TE_IOERR_DELETE
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 TE_IOERR_NOMEM
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 TE_IOERR_ACCESS
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 TE_IOERR_LOCK
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 TE_IOERR_CLOSE
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 SE (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 CACHE (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c TE_LOCKED | (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c Y (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 ITE_BUSY | (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 TEMPDIR (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 LITE_CANTOPEN |
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 001 /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 E 0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 002 /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 TE_OPEN_CREATE
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 004 /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 CLOSE 0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 008 /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 E 0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 010 /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 Y 0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 020 /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 TE_OPEN_MAIN_DB
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 100 /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 TE_OPEN_TEMP_DB
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 200 /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 T_DB 0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 400 /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 RNAL 0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 800 /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 RNAL 0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 AL 0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 OURNAL 0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 TE_OPEN_NOMUTEX
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 X 0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 CHE 0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 ACHE 0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5620: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
5630: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 REF: Device Char
5640: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a acteristics.**.*
5650: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70 * The xDeviceCap
5660: 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 abilities method
5670: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
5680: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 _io_methods].**
5690: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 object returns a
56a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
56b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 is a vector of t
56c0: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 he these.** bit
56d0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e values expressin
56e0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 g I/O characteri
56f0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 stics of the mas
5700: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 s storage.** dev
5710: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 ice that holds t
5720: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 he file that the
5730: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
5740: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 hods].** refers
5750: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 to..**.** The SQ
5760: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5770: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
5780: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
5790: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
57a0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
57b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
57c0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
57d0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
57e0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
57f0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
5800: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
5810: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
5820: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
5830: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
5840: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
5850: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
5860: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
5870: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
5880: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
5890: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
58a0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
58b0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
58c0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
58d0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
58e0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
58f0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
5900: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
5910: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
5920: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
5930: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
5940: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
5950: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
5960: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
5970: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
5980: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
5990: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
59a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
59b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
59c0: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 0x00000001.#defi
59d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
59e0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 ATOMIC512
59f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5a00: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
5a10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 _IOCAP_ATOMIC1K
5a20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
5a30: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 00000004.#define
5a40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5a50: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 OMIC2K
5a60: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 0x00000008.
5a70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5a80: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 OCAP_ATOMIC4K
5a90: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
5aa0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 000010.#define S
5ab0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5ac0: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 IC8K
5ad0: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 0x00000020.#d
5ae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5af0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 AP_ATOMIC16K
5b00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5b10: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0040.#define SQL
5b20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
5b30: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 32K
5b40: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 0x00000080.#def
5b50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5b60: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 _ATOMIC64K
5b70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 0x000001
5b80: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
5b90: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
5ba0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 END 0
5bb0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e x00000200.#defin
5bc0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
5bd0: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 EQUENTIAL
5be0: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0x00000400
5bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5c00: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c IOCAP_UNDELETABL
5c10: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 E_WHEN_OPEN 0x0
5c20: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0000800../*.** C
5c30: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f API3REF: File Lo
5c40: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a cking Levels.**.
5c50: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f ** SQLite uses o
5c60: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
5c70: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
5c80: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 e second.** argu
5c90: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 ment to calls it
5ca0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c makes to the xL
5cb0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
5cc0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f k() methods.** o
5cd0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f f an [sqlite3_io
5ce0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
5cf0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
5d00: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 ITE_LOCK_NONE
5d10: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
5d20: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 SQLITE_LOCK_SHA
5d30: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 RED 1.#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
5d50: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 _RESERVED 2
5d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5d70: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 LOCK_PENDING
5d80: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
5d90: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
5da0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 VE 4../*.**
5db0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 CAPI3REF: Synchr
5dc0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 onization Type F
5dd0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 lags.**.** When
5de0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 SQLite invokes t
5df0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f he xSync() metho
5e00: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 d of an.** [sqli
5e10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
5e20: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 object it uses a
5e30: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a combination of.
5e40: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 ** these integer
5e50: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
5e60: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a econd argument..
5e70: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 **.** When the S
5e80: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
5e90: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 NLY flag is used
5ea0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
5eb0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 the.** sync oper
5ec0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 ation only needs
5ed0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 to flush data t
5ee0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 o mass storage.
5ef0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d Inode.** inform
5f00: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 ation need not b
5f10: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 e flushed. If th
5f20: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
5f30: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a s of the flag.**
5f40: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
5f50: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 NC_NORMAL, that
5f60: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 means to use nor
5f70: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 mal fsync() sema
5f80: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 ntics..** If the
5f90: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 lower four bits
5fa0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
5fb0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 NC_FULL, that me
5fc0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 ans.** to use Ma
5fd0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c c OS X style ful
5fe0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 lsync instead of
5ff0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 fsync()..*/.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
6010: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 _NORMAL 0
6020: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 x00002.#define S
6030: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
6040: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0x00003
6050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6060: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 SYNC_DATAONLY
6070: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 0x00010../*.*
6080: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
6090: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 nterface Open Fi
60a0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 le Handle.**.**
60b0: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 An [sqlite3_file
60c0: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 ] object represe
60d0: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 nts an open file
60e0: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c in the .** [sql
60f0: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e ite3_vfs | OS in
6100: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 terface layer].
6110: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
6120: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c nterface.** impl
6130: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
6140: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 .** want to subc
6150: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 lass this object
6160: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 by appending ad
6170: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a ditional fields.
6180: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e ** for their own
6190: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 use. The pMeth
61a0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 ods entry is a p
61b0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
61c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
61d0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 ods] object that
61e0: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 defines methods
61f0: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a for performing.
6200: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e ** I/O operation
6210: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 s on the open fi
6220: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 le..*/.typedef s
6230: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
6240: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b le sqlite3_file;
6250: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
6260: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 file {. const s
6270: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
6280: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f _methods *pMetho
6290: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 ds; /* Methods
62a0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 for an open file
62b0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
62c0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
62d0: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 face File Virtua
62e0: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 l Methods Object
62f0: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c .**.** Every fil
6300: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 e opened by the
6310: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f [sqlite3_vfs] xO
6320: 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c pen method popul
6330: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 ates an.** [sqli
6340: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
6350: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f (or, more commo
6360: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 nly, a subclass
6370: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
6380: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 e3_file] object)
6390: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
63a0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
63b0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a f this object..*
63c0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 * This object de
63d0: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 fines the method
63e0: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 s used to perfor
63f0: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 m various operat
6400: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 ions.** against
6410: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 the open file re
6420: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 presented by the
6430: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
6440: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 object..**.** If
6450: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f the xOpen metho
6460: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 d sets the sqlit
6470: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
6480: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 element .** to
6490: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
64a0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c er, then the sql
64b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e ite3_io_methods.
64c0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a xClose method.**
64d0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 may be invoked
64e0: 65 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65 even if the xOpe
64f0: 6e 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 n reported that
6500: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a it failed. The.
6510: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 ** only way to p
6520: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f revent a call to
6530: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e xClose followin
6540: 67 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e g a failed xOpen
6550: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78 .** is for the x
6560: 4f 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20 Open to set the
6570: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
6580: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f thods element to
6590: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 NULL..**.** The
65a0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
65b0: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 to xSync may be
65c0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 one of [SQLITE_S
65d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a YNC_NORMAL] or.*
65e0: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 * [SQLITE_SYNC_F
65f0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ULL]. The first
6600: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e choice is the n
6610: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a ormal fsync()..*
6620: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f * The second cho
6630: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 ice is a Mac OS
6640: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
6650: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 . The [SQLITE_S
6660: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a YNC_DATAONLY].**
6670: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 flag may be ORe
6680: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 d in to indicate
6690: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 that only the d
66a0: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a ata of the file.
66b0: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 ** and not its i
66c0: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 node needs to be
66d0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 synced..**.** T
66e0: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 he integer value
66f0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 s to xLock() and
6700: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f xUnlock() are o
6710: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ne of.** <ul>.**
6720: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
6730: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 CK_NONE],.** <li
6740: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 > [SQLITE_LOCK_S
6750: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 HARED],.** <li>
6760: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
6770: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 ERVED],.** <li>
6780: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
6790: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 DING], or.** <li
67a0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 > [SQLITE_LOCK_E
67b0: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f XCLUSIVE]..** </
67c0: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 ul>.** xLock() i
67d0: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ncreases the loc
67e0: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 k. xUnlock() dec
67f0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
6800: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 .** The xCheckRe
6810: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 servedLock() met
6820: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 hod checks wheth
6830: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 er any database
6840: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 connection,.** e
6850: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 ither in this pr
6860: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 ocess or in some
6870: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 other process,
6880: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 is holding a RES
6890: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e ERVED,.** PENDIN
68a0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 G, or EXCLUSIVE
68b0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 lock on the file
68c0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 . It returns tr
68d0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 ue.** if such a
68e0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 lock exists and
68f0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e false otherwise.
6900: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 .**.** The xFile
6910: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 Control() method
6920: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e is a generic in
6930: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c terface that all
6940: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 ows custom.** VF
6950: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
6960: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f s to directly co
6970: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 ntrol an open fi
6980: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 le using the.**
6990: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
69a0: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
69b0: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ce. The second
69c0: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 "op" argument is
69d0: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f an.** integer o
69e0: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 pcode. The thir
69f0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 d argument is a
6a00: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 generic pointer
6a10: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 intended to.** p
6a20: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 oint to a struct
6a30: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e ure that may con
6a40: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f tain arguments o
6a50: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 r space in which
6a60: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 to.** write ret
6a70: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 urn values. Pot
6a80: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 ential uses for
6a90: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d xFileControl() m
6aa0: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 ight be.** funct
6ab0: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 ions to enable b
6ac0: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 locking locks wi
6ad0: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 th timeouts, to
6ae0: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f change the.** lo
6af0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 cking strategy (
6b00: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 for example to u
6b10: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b se dot-file lock
6b20: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a s), to inquire.*
6b30: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 * about the stat
6b40: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 us of a lock, or
6b50: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 to break stale
6b60: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 locks. The SQLi
6b70: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 te.** core reser
6b80: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 ves all opcodes
6b90: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f less than 100 fo
6ba0: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a r its own use..*
6bb0: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 * A [SQLITE_FCNT
6bc0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 L_LOCKSTATE | li
6bd0: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c st of opcodes] l
6be0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 ess than 100 is
6bf0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 available..** Ap
6c00: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
6c10: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 define a custom
6c20: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
6c30: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f hod should use o
6c40: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 pcodes.** greate
6c50: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 r than 100 to av
6c60: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a oid conflicts..*
6c70: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 *.** The xSector
6c80: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 Size() method re
6c90: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 turns the sector
6ca0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 size of the.**
6cb0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 device that unde
6cc0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 rlies the file.
6cd0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 The sector size
6ce0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d is the.** minim
6cf0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 um write that ca
6d00: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 n be performed w
6d10: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e ithout disturbin
6d20: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 g.** other bytes
6d30: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 in the file. T
6d40: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 he xDeviceCharac
6d50: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d teristics().** m
6d60: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
6d70: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 bit vector descr
6d80: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 ibing behaviors
6d90: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c of the.** underl
6da0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a ying device:.**.
6db0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
6dc0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
6dd0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 OMIC].** <li> [S
6de0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6df0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC512].** <li> [
6e00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6e10: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC1K].** <li> [
6e20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6e30: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC2K].** <li> [
6e40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6e50: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC4K].** <li> [
6e60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6e70: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC8K].** <li> [
6e80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6e90: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC16K].** <li>
6ea0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
6eb0: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC32K].** <li>
6ec0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
6ed0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC64K].** <li
6ee0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
6ef0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 SAFE_APPEND].**
6f00: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6f10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a AP_SEQUENTIAL].*
6f20: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
6f30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6f40: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
6f50: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
6f60: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
6f70: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
6f80: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6f90: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
6fa0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
6fb0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
6fc0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
6fd0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
6fe0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
6ff0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
7000: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
7010: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
7020: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
7030: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
7040: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
7050: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
7060: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
7070: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
7080: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
7090: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
70a0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
70b0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
70c0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
70d0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
70e0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
70f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
7100: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
7110: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
7120: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
7130: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
7140: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
7150: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
7160: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 e()..**.** If xR
7170: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 ead() returns SQ
7180: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 LITE_IOERR_SHORT
7190: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c _READ it must al
71a0: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 so fill.** in th
71b0: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e e unread portion
71c0: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 s of the buffer
71d0: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 with zeros. A V
71e0: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 FS that.** fails
71f0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
7200: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 ort reads might
7210: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 seem to work. H
7220: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 owever,.** failu
7230: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 re to zero-fill
7240: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c short reads will
7250: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 eventually lead
7260: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 to.** database
7270: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 corruption..*/.t
7280: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
7290: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
72a0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
72b0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
72c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b te3_io_methods {
72d0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
72e0: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 . int (*xClose)
72f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
7300: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 . int (*xRead)(
7310: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 sqlite3_file*, v
7320: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 oid*, int iAmt,
7330: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
7340: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 fst);. int (*xW
7350: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 rite)(sqlite3_fi
7360: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a le*, const void*
7370: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
7380: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
7390: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 ;. int (*xTrunc
73a0: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ate)(sqlite3_fil
73b0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
73c0: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 4 size);. int (
73d0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
73e0: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 file*, int flags
73f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 );. int (*xFile
7400: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
7410: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 le*, sqlite3_int
7420: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 64 *pSize);. in
7430: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 t (*xLock)(sqlit
7440: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
7450: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 int (*xUnlock)
7460: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
7470: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 int);. int (*xC
7480: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b heckReservedLock
7490: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
74a0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
74b0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e int (*xFileCon
74c0: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 trol)(sqlite3_fi
74d0: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 le*, int op, voi
74e0: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 d *pArg);. int
74f0: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 (*xSectorSize)(s
7500: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
7510: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 int (*xDeviceCh
7520: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 aracteristics)(s
7530: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
7540: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
7550: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
7560: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 version 1 */. i
7570: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 nt (*xShmMap)(sq
7580: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
7590: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 iPg, int pgsz,
75a0: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 int, void volati
75b0: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 le**);. int (*x
75c0: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 ShmLock)(sqlite3
75d0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 _file*, int offs
75e0: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 et, int n, int f
75f0: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a lags);. void (*
7600: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c xShmBarrier)(sql
7610: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
7620: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 nt (*xShmUnmap)(
7630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
7640: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a nt deleteFlag);.
7650: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f /* Methods abo
7660: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 ve are valid for
7670: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 version 2 */.
7680: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 /* Additional me
7690: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 thods may be add
76a0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
76b0: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a eases */.};../*.
76c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 ** CAPI3REF: Sta
76d0: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 ndard File Contr
76e0: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a ol Opcodes.**.**
76f0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
7700: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 onstants are opc
7710: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 odes for the xFi
7720: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
7730: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
7740: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
7750: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 object and for t
7760: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
7770: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 _control()].** i
7780: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
7790: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
77a0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 L_LOCKSTATE] opc
77b0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 ode is used for
77c0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 debugging. This
77d0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 .** opcode cause
77e0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 s the xFileContr
77f0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 ol method to wri
7800: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 te the current s
7810: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c tate of.** the l
7820: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c ock (one of [SQL
7830: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 ITE_LOCK_NONE],
7840: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 [SQLITE_LOCK_SHA
7850: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 RED],.** [SQLITE
7860: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c _LOCK_RESERVED],
7870: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 [SQLITE_LOCK_PE
7880: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 NDING], or [SQLI
7890: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
78a0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 E]).** into an i
78b0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 nteger that the
78c0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f pArg argument po
78d0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 ints to. This ca
78e0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 pability.** is u
78f0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 sed during testi
7900: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 ng and only need
7910: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 s to be supporte
7920: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 d when SQLITE_TE
7930: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 ST.** is defined
7940: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ..**.** The [SQL
7950: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
7960: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 INT] opcode is u
7970: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f sed by SQLite to
7980: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a give the VFS.**
7990: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 layer a hint of
79a0: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 how large the d
79b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c atabase file wil
79c0: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 l grow to be dur
79d0: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 ing the.** curre
79e0: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 nt transaction.
79f0: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f This hint is no
7a00: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 t guaranteed to
7a10: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 be accurate but
7a20: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 it.** is often c
7a30: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 lose. The under
7a40: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 lying VFS might
7a50: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c choose to preall
7a60: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a ocate database.*
7a70: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 * file space bas
7a80: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 ed on this hint
7a90: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 in order to help
7aa0: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 writes to the d
7ab0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
7ac0: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2f 0a 23 run faster..*/.#
7ad0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
7ae0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 NTL_LOCKSTATE
7af0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
7b00: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 QLITE_GET_LOCKPR
7b10: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 OXYFILE 2.#
7b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
7b30: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
7b40: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
7b50: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f QLITE_LAST_ERRNO
7b60: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 4.#
7b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
7b80: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 NTL_SIZE_HINT
7b90: 20 20 20 20 20 35 0a 0a 2f 2a 0a 2a 2a 20 43 41 5../*.** CA
7ba0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 PI3REF: Mutex Ha
7bb0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d ndle.**.** The m
7bc0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 utex module with
7bd0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 in SQLite define
7be0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 s [sqlite3_mutex
7bf0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 ] to be an.** ab
7c00: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 stract type for
7c10: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 a mutex object.
7c20: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
7c30: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 never looks.**
7c40: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 at the internal
7c50: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f representation o
7c60: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 f an [sqlite3_mu
7c70: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a tex]. It only.*
7c80: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 * deals with poi
7c90: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 nters to the [sq
7ca0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a lite3_mutex] obj
7cb0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 ect..**.** Mutex
7cc0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 es are created u
7cd0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 sing [sqlite3_mu
7ce0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f tex_alloc()]..*/
7cf0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
7d00: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 sqlite3_mutex sq
7d10: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a lite3_mutex;../*
7d20: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
7d30: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 Interface Objec
7d40: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 t.**.** An insta
7d50: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 nce of the sqlit
7d60: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 e3_vfs object de
7d70: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 fines the interf
7d80: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 ace between.** t
7d90: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 he SQLite core a
7da0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
7db0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 g operating syst
7dc0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a em. The "vfs".*
7dd0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 * in the name of
7de0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e the object stan
7df0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 ds for "virtual
7e00: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a file system"..**
7e10: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 .** The value of
7e20: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 the iVersion fi
7e30: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 eld is initially
7e40: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 1 but may be la
7e50: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 rger in.** futur
7e60: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
7e70: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 Lite. Additiona
7e80: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 l fields may be
7e90: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 appended to this
7ea0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 .** object when
7eb0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c the iVersion val
7ec0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e ue is increased.
7ed0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 Note that the
7ee0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 structure.** of
7ef0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
7f00: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 object changes i
7f10: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f n the transactio
7f20: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c n between.** SQL
7f30: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
7f40: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 9 and 3.6.0 and
7f50: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e yet the iVersion
7f60: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a field was not.*
7f70: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a * modified..**.*
7f80: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 * The szOsFile f
7f90: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 ield is the size
7fa0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 of the subclass
7fb0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ed [sqlite3_file
7fc0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 ].** structure u
7fd0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e sed by this VFS.
7fe0: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 mxPathname is
7ff0: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 the maximum leng
8000: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e th of.** a pathn
8010: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e ame in this VFS.
8020: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 .**.** Registere
8030: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 d sqlite3_vfs ob
8040: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f jects are kept o
8050: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 n a linked list
8060: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 formed by.** the
8070: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 pNext pointer.
8080: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 The [sqlite3_vf
8090: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a s_register()].**
80a0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 and [sqlite3_vf
80b0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 s_unregister()]
80c0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 interfaces manag
80d0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 e this list.** i
80e0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 n a thread-safe
80f0: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 way. The [sqlit
8100: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 e3_vfs_find()] i
8110: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 nterface.** sear
8120: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 ches the list.
8130: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c Neither the appl
8140: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 ication code nor
8150: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c the VFS.** impl
8160: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c ementation shoul
8170: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 d use the pNext
8180: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
8190: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 he pNext field i
81a0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 s the only field
81b0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f in the sqlite3_
81c0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 vfs.** structure
81d0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
81e0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 l ever modify.
81f0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 SQLite will only
8200: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f access.** or mo
8210: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 dify this field
8220: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 while holding a
8230: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 particular stati
8240: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 c mutex..** The
8250: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
8260: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 ld never modify
8270: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 anything within
8280: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a the sqlite3_vfs.
8290: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 ** object once t
82a0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 he object has be
82b0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a en registered..*
82c0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 *.** The zName f
82d0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e ield holds the n
82e0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d ame of the VFS m
82f0: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 odule. The name
8300: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 must.** be uniq
8310: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 ue across all VF
8320: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a S modules..**.**
8330: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 SQLite will gua
8340: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 rantee that the
8350: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 zFilename parame
8360: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 ter to xOpen.**
8370: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c is either a NULL
8380: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 pointer or stri
8390: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ng obtained.** f
83a0: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d rom xFullPathnam
83b0: 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 e(). SQLite fur
83c0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 ther guarantees
83d0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 that.** the stri
83e0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 ng will be valid
83f0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 and unchanged u
8400: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 ntil xClose() is
8410: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 .** called. Beca
8420: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 use of the previ
8430: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a ous sentence,.**
8440: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
8450: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 le] can safely s
8460: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 tore a pointer t
8470: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d o the.** filenam
8480: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f e if it needs to
8490: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 remember the fi
84a0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 lename for some
84b0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 reason..** If th
84c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
84d0: 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69 meter is xOpen i
84e0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
84f0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d then xOpen.** m
8500: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f ust invent its o
8510: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d wn temporary nam
8520: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 e for the file.
8530: 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a Whenever the .*
8540: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 * xFilename para
8550: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 meter is NULL it
8560: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 will also be th
8570: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a e case that the.
8580: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 ** flags paramet
8590: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 er will include
85a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
85b0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a ETEONCLOSE]..**.
85c0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 ** The flags arg
85d0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 ument to xOpen()
85e0: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 includes all bi
85f0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 ts set in.** the
8600: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
8610: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
8620: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b _v2()]. Or if [
8630: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a sqlite3_open()].
8640: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f ** or [sqlite3_o
8650: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 pen16()] is used
8660: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 , then flags inc
8670: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a ludes at least.*
8680: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 * [SQLITE_OPEN_R
8690: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c EADWRITE] | [SQL
86a0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
86b0: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 . .** If xOpen()
86c0: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 opens a file re
86d0: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 ad-only then it
86e0: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 sets *pOutFlags
86f0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 to.** include [S
8700: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
8710: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 NLY]. Other bit
8720: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 s in *pOutFlags
8730: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a may be set..**.*
8740: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c * SQLite will al
8750: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
8760: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
8770: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 s to the xOpen()
8780: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 .** call, depend
8790: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 ing on the objec
87a0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a t being opened:.
87b0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
87c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
87d0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _MAIN_DB].** <li
87e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
87f0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a MAIN_JOURNAL].**
8800: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
8810: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 PEN_TEMP_DB].**
8820: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
8830: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d EN_TEMP_JOURNAL]
8840: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
8850: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
8860: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
8870: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
8880: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
8890: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 [SQLITE_OPEN_MAS
88a0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 TER_JOURNAL].**
88b0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
88c0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 file I/O impleme
88d0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 ntation can use
88e0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 the object type
88f0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e flags to.** chan
8900: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 ge the way it de
8910: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 als with files.
8920: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e For example, an
8930: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
8940: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 that does not ca
8950: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 re about crash r
8960: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 ecovery or rollb
8970: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a ack might make.*
8980: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 * the open of a
8990: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e journal file a n
89a0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f o-op. Writes to
89b0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f this journal wo
89c0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e uld.** also be n
89d0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 o-ops, and any a
89e0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 ttempt to read t
89f0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 he journal would
8a00: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 return.** SQLIT
8a10: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 E_IOERR. Or the
8a20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
8a30: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 might recognize
8a40: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a that a database.
8a50: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 ** file will be
8a60: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e doing page-align
8a70: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 ed sector reads
8a80: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 and writes in a
8a90: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 random.** order
8aa0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 and set up its I
8ab0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 /O subsystem acc
8ac0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ordingly..**.**
8ad0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 SQLite might als
8ae0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
8af0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
8b00: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 to the xOpen me
8b10: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e thod:.**.** <ul>
8b20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8b30: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
8b40: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 OSE].** <li> [SQ
8b50: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
8b60: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a IVE].** </ul>.**
8b70: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
8b80: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
8b90: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 SE] flag means t
8ba0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
8bb0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 e.** deleted whe
8bc0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 n it is closed.
8bd0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 The [SQLITE_OPE
8be0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
8bf0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 .** will be set
8c00: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 for TEMP databa
8c10: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e ses, journals an
8c20: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c d for subjournal
8c30: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 s..**.** The [SQ
8c40: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
8c50: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 IVE] flag is alw
8c60: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a ays used in conj
8c70: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 unction.** with
8c80: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
8c90: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 _CREATE] flag, w
8ca0: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 hich are both di
8cb0: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 rectly.** analog
8cc0: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 ous to the O_EXC
8cd0: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c L and O_CREAT fl
8ce0: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 ags of the POSIX
8cf0: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 open().** API.
8d00: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e The SQLITE_OPEN
8d10: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c _EXCLUSIVE flag,
8d20: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 when paired wit
8d30: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 h the .** SQLITE
8d40: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 _OPEN_CREATE, is
8d50: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 used to indicat
8d60: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 e that file shou
8d70: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 ld always.** be
8d80: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 created, and tha
8d90: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 t it is an error
8da0: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 if it already e
8db0: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 xists..** It is
8dc0: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 <i>not</i> used
8dd0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 to indicate the
8de0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f file should be o
8df0: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 pened .** for ex
8e00: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a clusive access..
8e10: 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20 73 **.** At least s
8e20: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 zOsFile bytes of
8e30: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f memory are allo
8e40: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a cated by SQLite.
8e50: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 ** to hold the
8e60: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 [sqlite3_file] s
8e70: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 tructure passed
8e80: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 as the third.**
8e90: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 argument to xOpe
8ea0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 n. The xOpen me
8eb0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 thod does not ha
8ec0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ve to.** allocat
8ed0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b e the structure;
8ee0: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 it should just
8ef0: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 fill it in. Not
8f00: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f e that.** the xO
8f10: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 pen method must
8f20: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f set the sqlite3_
8f30: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f file.pMethods to
8f40: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c either.** a val
8f50: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d id [sqlite3_io_m
8f60: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f ethods] object o
8f70: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 r to NULL. xOpe
8f80: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 n must do.** thi
8f90: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 s even if the op
8fa0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 en fails. SQLit
8fb0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 e expects that t
8fc0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
8fd0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d pMethods.** elem
8fe0: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 ent will be vali
8ff0: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 d after xOpen re
9000: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 turns regardless
9010: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a of the success.
9020: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 ** or failure of
9030: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e the xOpen call.
9040: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 .**.** The flags
9050: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 argument to xAc
9060: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 cess() may be [S
9070: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
9080: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 STS].** to test
9090: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 for the existenc
90a0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 e of a file, or
90b0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
90c0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 EADWRITE] to.**
90d0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
90e0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 ile is readable
90f0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 and writable, or
9100: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
9110: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 READ].** to test
9120: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
9130: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 is at least read
9140: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 able. The file
9150: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 can be a.** dir
9160: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 ectory..**.** SQ
9170: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 Lite will always
9180: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 allocate at lea
9190: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 st mxPathname+1
91a0: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a bytes for the.**
91b0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 output buffer x
91c0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 FullPathname. T
91d0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 he exact size of
91e0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
91f0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 er.** is also pa
9200: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 ssed as a parame
9210: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 ter to both met
9220: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 hods. If the out
9230: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
9240: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 not large enoug
9250: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f h, [SQLITE_CANTO
9260: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 PEN] should be r
9270: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 eturned. Since t
9280: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 his is.** handle
9290: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 d as a fatal err
92a0: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 or by SQLite, vf
92b0: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
92c0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f s should endeavo
92d0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 r.** to prevent
92e0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 this by setting
92f0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 mxPathname to a
9300: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 sufficiently lar
9310: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 ge value..**.**
9320: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 The xRandomness(
9330: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 ), xSleep(), xCu
9340: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 rrentTime(), and
9350: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
9360: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 64().** interfac
9370: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 es are not stric
9380: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 tly a part of th
9390: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 e filesystem, bu
93a0: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e t they are.** in
93b0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 cluded in the VF
93c0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 S structure for
93d0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a completeness..**
93e0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
93f0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 () function atte
9400: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e mpts to return n
9410: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f Bytes bytes.** o
9420: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 f good-quality r
9430: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a andomness into z
9440: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e Out. The return
9450: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 value is.** the
9460: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f actual number o
9470: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f f bytes of rando
9480: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a mness obtained..
9490: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 ** The xSleep()
94a0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 method causes th
94b0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 e calling thread
94c0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 to sleep for at
94d0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 .** least the nu
94e0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 mber of microsec
94f0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 onds given. The
9500: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a xCurrentTime().
9510: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e ** method return
9520: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e s a Julian Day N
9530: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 umber for the cu
9540: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 rrent date and t
9550: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 ime as.** a floa
9560: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
9570: 2e 0a 2a 2a 20 54 68 65 20 78 43 75 72 72 65 6e ..** The xCurren
9580: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 tTimeInt64() met
9590: 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 hod returns, as
95a0: 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 an integer, the
95b0: 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 Julian.** Day Nu
95c0: 6d 62 65 72 20 6d 75 6c 74 69 70 6c 65 64 20 62 mber multipled b
95d0: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 y 86400000 (the
95e0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
95f0: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 econds in .** a
9600: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 24-hour day). .
9610: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 ** ^SQLite will
9620: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 use the xCurrent
9630: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 TimeInt64() meth
9640: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 od to get the cu
9650: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e rrent.** date an
9660: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d d time if that m
9670: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 ethod is availab
9680: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 le (if iVersion
9690: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 is 2 or .** grea
96a0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 ter and the func
96b0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
96c0: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 not NULL) and wi
96d0: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 ll fall back.**
96e0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 to xCurrentTime(
96f0: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d ) if xCurrentTim
9700: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 eInt64() is unav
9710: 61 69 6c 61 62 6c 65 2e 0a 2a 2f 0a 74 79 70 65 ailable..*/.type
9720: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
9730: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 e3_vfs sqlite3_v
9740: 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 fs;.struct sqlit
9750: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 e3_vfs {. int i
9760: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 Version;
9770: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 /* Structure
9780: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 version number
9790: 28 63 75 72 72 65 6e 74 6c 79 20 32 29 20 2a 2f (currently 2) */
97a0: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b . int szOsFile;
97b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
97c0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 ize of subclasse
97d0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a d sqlite3_file *
97e0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 /. int mxPathna
97f0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 me; /*
9800: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 Maximum file pat
9810: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a hname length */.
9820: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 sqlite3_vfs *p
9830: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 Next; /* Ne
9840: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 xt registered VF
9850: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 S */. const cha
9860: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 r *zName;
9870: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 /* Name of this
9880: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 virtual file sys
9890: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tem */. void *p
98a0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
98b0: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 /* Pointer to
98c0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 application-spec
98d0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 ific data */. i
98e0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
98f0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
9900: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c char *zName, sql
9910: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 ite3_file*,.
9920: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 int f
9930: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 lags, int *pOutF
9940: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 lags);. int (*x
9950: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f Delete)(sqlite3_
9960: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
9970: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e *zName, int syn
9980: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 cDir);. int (*x
9990: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f Access)(sqlite3_
99a0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
99b0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 *zName, int fla
99c0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 gs, int *pResOut
99d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c );. int (*xFull
99e0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 Pathname)(sqlite
99f0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
9a00: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e ar *zName, int n
9a10: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 Out, char *zOut)
9a20: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f ;. void *(*xDlO
9a30: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 pen)(sqlite3_vfs
9a40: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
9a50: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 Filename);. voi
9a60: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 d (*xDlError)(sq
9a70: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
9a80: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 nByte, char *zEr
9a90: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a rMsg);. void (*
9aa0: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 (*xDlSym)(sqlite
9ab0: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 3_vfs*,void*, co
9ac0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f nst char *zSymbo
9ad0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 l))(void);. voi
9ae0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 d (*xDlClose)(sq
9af0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 lite3_vfs*, void
9b00: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e *);. int (*xRan
9b10: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 domness)(sqlite3
9b20: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 _vfs*, int nByte
9b30: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
9b40: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 int (*xSleep)(s
9b50: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
9b60: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a microseconds);.
9b70: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 int (*xCurrent
9b80: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 Time)(sqlite3_vf
9b90: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 s*, double*);.
9ba0: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 int (*xGetLastEr
9bb0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ror)(sqlite3_vfs
9bc0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b *, int, char *);
9bd0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d . /*. ** The m
9be0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
9bf0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 in version 1 of
9c00: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 the sqlite_vfs
9c10: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 object. ** defi
9c20: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 nition. Those t
9c30: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 hat follow are a
9c40: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 dded in version
9c50: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 2 or later. */.
9c60: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 int (*xCurrent
9c70: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 TimeInt64)(sqlit
9c80: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 e3_vfs*, sqlite3
9c90: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 _int64*);. /*.
9ca0: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 ** The methods
9cb0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 above are in ver
9cc0: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 sions 1 and 2 of
9cd0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 the sqlite_vfs
9ce0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 object.. ** New
9cf0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
9d00: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 ppended in figur
9d10: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 e versions. The
9d20: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 iVersion. ** v
9d30: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d alue will increm
9d40: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 ent whenever thi
9d50: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f s happens. . */
9d60: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
9d70: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 REF: Flags for t
9d80: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d he xAccess VFS m
9d90: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ethod.**.** Thes
9da0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
9db0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nts can be used
9dc0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 as the third par
9dd0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
9de0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
9df0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 of an [sqlite3_v
9e00: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 fs] object. The
9e10: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 y determine.** w
9e20: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d hat kind of perm
9e30: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 issions the xAcc
9e40: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f ess method is lo
9e50: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 oking for..** Wi
9e60: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
9e70: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 _EXISTS, the xAc
9e80: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 cess method.** s
9e90: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 imply checks whe
9ea0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 ther the file ex
9eb0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 ists..** With SQ
9ec0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
9ed0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 WRITE, the xAcce
9ee0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
9ef0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
9f00: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 named directory
9f10: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 is both readable
9f20: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a and writable.**
9f30: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 (in other words
9f40: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 , if files can b
9f50: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 e added, removed
9f60: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 , and renamed wi
9f70: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 thin.** the dire
9f80: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 ctory)..** The S
9f90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
9fa0: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 DWRITE constant
9fb0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 is currently use
9fc0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a d only by the.**
9fd0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
9fe0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 ectory pragma],
9ff0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c though this coul
a000: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 d change in a fu
a010: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 ture.** release
a020: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 of SQLite..** Wi
a030: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
a040: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 _READ, the xAcce
a050: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
a060: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
a070: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
a080: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 . The SQLITE_AC
a090: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 CESS_READ consta
a0a0: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 nt is.** current
a0b0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 ly unused, thoug
a0c0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 h it might be us
a0d0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 ed in a future r
a0e0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c elease of.** SQL
a0f0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ite..*/.#define
a100: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
a110: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e ISTS 0.#defin
a120: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
a130: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a READWRITE 1 /*
a140: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 Used by PRAGMA
a150: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
a160: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tory */.#define
a170: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
a180: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 AD 2 /* U
a190: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 nused */../*.**
a1a0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
a1b0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b for the xShmLock
a1c0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
a1d0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
a1e0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
a1f0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 the various loc
a200: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a king operations.
a210: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 ** allowed by th
a220: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
a230: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f d of [sqlite3_io
a240: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a _methods]. The.
a250: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 ** following are
a260: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 the only legal
a270: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 combinations of
a280: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 flags to the.**
a290: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a xShmLock method:
a2a0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
a2b0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f li> SQLITE_SHM_
a2c0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
a2d0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e M_SHARED.** <li>
a2e0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 SQLITE_SHM_LOC
a2f0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
a300: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e XCLUSIVE.** <li>
a310: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c SQLITE_SHM_UNL
a320: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
a330: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
a340: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
a350: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
a360: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 EXCLUSIVE.** </u
a370: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e l>.**.** When un
a380: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d locking, the sam
a390: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c e SHARED or EXCL
a3a0: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 USIVE flag must
a3b0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a be supplied as.*
a3c0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 * was given no t
a3d0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
a3e0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 lock. .**.** T
a3f0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
a400: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f od can transitio
a410: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b n between unlock
a420: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 ed and SHARED or
a430: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f .** between unlo
a440: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 cked and EXCLUSI
a450: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 VE. It cannot t
a460: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
a470: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 n SHARED.** and
a480: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 EXCLUSIVE..*/.#d
a490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
a4a0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a _UNLOCK 1.
a4b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
a4c0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 HM_LOCK
a4d0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
a4e0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 _SHM_SHARED
a4f0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
a500: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
a510: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8../*.** CAP
a520: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 I3REF: Maximum x
a530: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a ShmLock index.**
a540: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
a550: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 method on [sqli
a560: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
a570: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a may use values.*
a580: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 * between 0 and
a590: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 this upper bound
a5a0: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 as its "offset"
a5b0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 argument..** Th
a5c0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 e SQLite core wi
a5d0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 ll never attempt
a5e0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 to acquire or r
a5f0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b elease a.** lock
a600: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 outside of this
a610: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e range.*/.#defin
a620: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f e SQLITE_SHM_NLO
a630: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a CK 8.../*
a640: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
a650: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c itialize The SQL
a660: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a ite Library.**.*
a670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
a680: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
a690: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 ine initializes
a6a0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 the.** SQLite li
a6b0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c brary. ^The sql
a6c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
a6d0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c routine.** deall
a6e0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 ocates any resou
a6f0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 rces that were a
a700: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 llocated by sqli
a710: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
a720: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
a730: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 nes are designed
a740: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 to aid in proce
a750: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
a760: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 n and.** shutdow
a770: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 n on embedded sy
a780: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 stems. Workstat
a790: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ion applications
a7a0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 using.** SQLite
a7b0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 normally do not
a7c0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 need to invoke
a7d0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 either of these
a7e0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
a7f0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
a800: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
a810: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
a820: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a call if it is.*
a830: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 * the first time
a840: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
a850: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
a860: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 during the life
a870: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 time of.** the p
a880: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 rocess, or if it
a890: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 is the first ti
a8a0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 me sqlite3_initi
a8b0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
a8c0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
a8d0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
a8e0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 3_shutdown(). ^
a8f0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 (Only an effecti
a900: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 ve call.** of sq
a910: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
a920: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 () does any init
a930: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c ialization. All
a940: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 other calls.**
a950: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d are harmless no-
a960: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 ops.)^.**.** A c
a970: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
a980: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 hutdown() is an
a990: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c "effective" call
a9a0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
a9b0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 rst.** call to s
a9c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
a9d0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 ) since the last
a9e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
a9f0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a ize(). ^(Only.*
aa00: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 * an effective c
aa10: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
aa20: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 hutdown() does a
aa30: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 ny deinitializat
aa40: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 ion..** All othe
aa50: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f r valid calls to
aa60: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
aa70: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 n() are harmless
aa80: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a no-ops.)^.**.**
aa90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
aaa0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 tialize() interf
aab0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 ace is threadsaf
aac0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 e, but sqlite3_s
aad0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 hutdown().** is
aae0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 not. The sqlite
aaf0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 3_shutdown() int
ab00: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 erface must only
ab10: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
ab20: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 a.** single thre
ab30: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 ad. All open [d
ab40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
ab50: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f ons] must be clo
ab60: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f sed and all.** o
ab70: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f ther SQLite reso
ab80: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 urces must be de
ab90: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 allocated prior
aba0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 to invoking.** s
abb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
abc0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f )..**.** Among o
abd0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 ther things, ^sq
abe0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
abf0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a () will invoke.*
ac00: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
ac10: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c t(). Similarly,
ac20: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f ^sqlite3_shutdo
ac30: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 wn().** will inv
ac40: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 oke sqlite3_os_e
ac50: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nd()..**.** ^The
ac60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
ac70: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ize() routine re
ac80: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
ac90: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a ] on success..**
aca0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 ^If for some re
acb0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e ason, sqlite3_in
acc0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e itialize() is un
acd0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 able to initiali
ace0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 ze.** the librar
acf0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 y (perhaps it is
ad00: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
ad10: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 ate a needed res
ad20: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 ource such.** as
ad30: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 a mutex) it ret
ad40: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 urns an [error c
ad50: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 ode] other than
ad60: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
ad70: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
ad80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
ad90: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 tine is called i
ada0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e nternally by man
adb0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 y other.** SQLit
adc0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 e interfaces so
add0: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 that an applicat
ade0: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 ion usually does
adf0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 not need to.**
ae00: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 invoke sqlite3_i
ae10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
ae20: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 ctly. For examp
ae30: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 le, [sqlite3_ope
ae40: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 n()].** calls sq
ae50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
ae60: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 () so the SQLite
ae70: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 library will be
ae80: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
ae90: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 * initialized wh
aea0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e en [sqlite3_open
aeb0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 ()] is called if
aec0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 it has not be i
aed0: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c nitialized.** al
aee0: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 ready. ^However
aef0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 , if SQLite is c
af00: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
af10: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
af20: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 TOINIT].** compi
af30: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
af40: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 then the automat
af50: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ic calls to sqli
af60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
af70: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 .** are omitted
af80: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
af90: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 ion must call sq
afa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
afb0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 () directly.** p
afc0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
afd0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
afe0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d nterface. For m
aff0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 aximum portabili
b000: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 ty,.** it is rec
b010: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
b020: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 plications alway
b030: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 s invoke sqlite3
b040: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a _initialize().**
b050: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 directly prior
b060: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
b070: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
b080: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c ace. Future rel
b090: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 eases.** of SQLi
b0a0: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 te may require t
b0b0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 his. In other w
b0c0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 ords, the behavi
b0d0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 or exhibited.**
b0e0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
b0f0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
b100: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
b110: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 IT] might become
b120: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 the.** default
b130: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 behavior in some
b140: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
b150: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
b160: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
b170: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 init() routine d
b180: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 oes operating-sy
b190: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a stem specific.**
b1a0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
b1b0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
b1c0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 brary. The sqli
b1d0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
b1e0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 routine undoes t
b1f0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c he effect of sql
b200: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
b210: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a Typical tasks.*
b220: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 * performed by t
b230: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e hese routines in
b240: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e clude allocation
b250: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e or deallocation
b260: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 .** of static re
b270: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c sources, initial
b280: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 ization of globa
b290: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 l variables,.**
b2a0: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 setting up a def
b2b0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
b2c0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 s] module, or se
b2d0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 tting up.** a de
b2e0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
b2f0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ion using [sqlit
b300: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
b310: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
b320: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
b330: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 invoke either s
b340: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
b350: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f .** or sqlite3_o
b360: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 s_end() directly
b370: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
b380: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 on should only i
b390: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
b3a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
b3b0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f d sqlite3_shutdo
b3c0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 wn(). The sqlit
b3d0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
b3e0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c interface is cal
b3f0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c led automaticall
b400: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 y by sqlite3_ini
b410: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a tialize() and.**
b420: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
b430: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 ) is called by s
b440: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
b450: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a ). Appropriate.
b460: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
b470: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ns for sqlite3_o
b480: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
b490: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
b4a0: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 are built into
b4b0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 SQLite when it i
b4c0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 s compiled for U
b4d0: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 nix, Windows, or
b4e0: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b OS/2..** When [
b4f0: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 custom builds |
b500: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 built for other
b510: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 platforms].** (u
b520: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
b530: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d _OS_OTHER=1] com
b540: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
b550: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 ion) the applica
b560: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 tion must supply
b570: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c a suitable impl
b580: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a ementation for.*
b590: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
b5a0: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
b5b0: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 os_end(). An ap
b5c0: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 plication-suppli
b5d0: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ed.** implementa
b5e0: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
b5f0: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c os_init() or sql
b600: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
b610: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 must return [SQ
b620: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
b630: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 ess and some oth
b640: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 er [error code]
b650: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e upon.** failure.
b660: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
b670: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 initialize(void)
b680: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 ;.int sqlite3_sh
b690: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e utdown(void);.in
b6a0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 t sqlite3_os_ini
b6b0: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c t(void);.int sql
b6c0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 ite3_os_end(void
b6d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
b6e0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 EF: Configuring
b6f0: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
b700: 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ry.**.** The sql
b710: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
b720: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
b730: 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 to make global c
b740: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
b750: 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 changes to SQLit
b760: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 e in order to tu
b770: 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 ne SQLite to the
b780: 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 specific needs
b790: 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
b7a0: 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 ation. The defa
b7b0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
b7c0: 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 n is recommended
b7d0: 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 for most.** app
b7e0: 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f lications and so
b7f0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
b800: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 usually not nec
b810: 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a essary. It is.*
b820: 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 * provided to su
b830: 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 pport rare appli
b840: 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 cations with unu
b850: 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a sual needs..**.*
b860: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
b870: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
b880: 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 is not threadsa
b890: 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 fe. The applica
b8a0: 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 tion.** must ins
b8b0: 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 ure that no othe
b8c0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
b8d0: 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 ces are invoked
b8e0: 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 by other.** thre
b8f0: 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 ads while sqlite
b900: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 3_config() is ru
b910: 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d nning. Furtherm
b920: 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e ore, sqlite3_con
b930: 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c fig().** may onl
b940: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 y be invoked pri
b950: 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e or to library in
b960: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 itialization usi
b970: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 ng.** [sqlite3_i
b980: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 nitialize()] or
b990: 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 after shutdown b
b9a0: 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 y [sqlite3_shutd
b9b0: 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 own()]..** ^If s
b9c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
b9d0: 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 is called after
b9e0: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
b9f0: 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 ize()] and befor
ba00: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 e.** [sqlite3_sh
ba10: 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 utdown()] then i
ba20: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 t will return SQ
ba30: 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 LITE_MISUSE..**
ba40: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 Note, however, t
ba50: 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e hat ^sqlite3_con
ba60: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c fig() can be cal
ba70: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 led as part of t
ba80: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
ba90: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 tion of an appli
baa0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b cation-defined [
bab0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
bac0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 )]..**.** The fi
bad0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
bae0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
baf0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a is an integer.*
bb00: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
bb10: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 _SINGLETHREAD |
bb20: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
bb30: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 tion] that deter
bb40: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 mines.** what pr
bb50: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 operty of SQLite
bb60: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 is to be config
bb70: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e ured. Subsequen
bb80: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 t arguments.** v
bb90: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ary depending on
bba0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
bbb0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
bbc0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e | configuration
bbd0: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 option].** in t
bbe0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
bbf0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 t..**.** ^When a
bc00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
bc10: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 ption is set, sq
bc20: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 lite3_config() r
bc30: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
bc40: 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f K]..** ^If the o
bc50: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e ption is unknown
bc60: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e or SQLite is un
bc70: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 able to set the
bc80: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 option.** then t
bc90: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
bca0: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b rns a non-zero [
bcb0: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a error code]..*/.
bcc0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 int sqlite3_conf
bcd0: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f ig(int, ...);../
bce0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
bcf0: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 onfigure databas
bd00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a e connections.**
bd10: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
bd20: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 db_config() inte
bd30: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
bd40: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 make configurat
bd50: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
bd60: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f o a [database co
bd70: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 nnection]. The
bd80: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d interface is sim
bd90: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 ilar to.** [sqli
bda0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 te3_config()] ex
bdb0: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 cept that the ch
bdc0: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 anges apply to a
bdd0: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 single.** [data
bde0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
bdf0: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 (specified in t
be00: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
be10: 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 t). The.** sqli
be20: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
be30: 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 interface should
be40: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d only be used im
be50: 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a mediately after.
be60: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
be70: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 connection is cr
be80: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c eated using [sql
be90: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a ite3_open()],.**
bea0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
beb0: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 ()], or [sqlite3
bec0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a _open_v2()]. .*
bed0: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
bee0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
bef0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c te3_db_config(D,
bf00: 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a V,...) is the.*
bf10: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
bf20: 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 verb - an intege
bf30: 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 r code that indi
bf40: 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 cates what.** as
bf50: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 pect of the [dat
bf60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
bf70: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 ] is being confi
bf80: 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e gured..** The on
bf90: 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 ly choice for th
bfa0: 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c is value is [SQL
bfb0: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
bfc0: 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 KASIDE]..** New
bfd0: 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 verbs are likely
bfe0: 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 to be added in
bff0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
c000: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 of SQLite..** Ad
c010: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
c020: 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 ts depend on the
c030: 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 verb..**.** ^Ca
c040: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 lls to sqlite3_d
c050: 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 b_config() retur
c060: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 n SQLITE_OK if a
c070: 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 nd only if.** th
c080: 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 e call is consid
c090: 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e ered successful.
c0a0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
c0b0: 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 db_config(sqlite
c0c0: 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3*, int op, ...)
c0d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
c0e0: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
c0f0: 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a tion Routines.**
c100: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
c110: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 of this object d
c120: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
c130: 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c face between SQL
c140: 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c ite.** and low-l
c150: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f evel memory allo
c160: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
c170: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 .**.** This obje
c180: 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e ct is used in on
c190: 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 ly one place in
c1a0: 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 the SQLite inter
c1b0: 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 face..** A point
c1c0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
c1d0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
c1e0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 is the argument
c1f0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
c200: 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 config()] when t
c210: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
c220: 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 option is.** [S
c230: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
c240: 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f LOC] or [SQLITE_
c250: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
c260: 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 ]. .** By creat
c270: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 ing an instance
c280: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a of this object.*
c290: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 * and passing it
c2a0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
c2b0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
c2c0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 FIG_MALLOC]).**
c2d0: 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 during configura
c2e0: 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 tion, an applica
c2f0: 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 tion can specify
c300: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a an alternative.
c310: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
c320: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 tion subsystem f
c330: 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 or SQLite to use
c340: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a for all of its.
c350: 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ** dynamic memor
c360: 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e y needs..**.** N
c370: 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 ote that SQLite
c380: 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 comes with sever
c390: 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d al [built-in mem
c3a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a ory allocators].
c3b0: 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 ** that are perf
c3c0: 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 ectly adequate f
c3d0: 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d or the overwhelm
c3e0: 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 ing majority of
c3f0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
c400: 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 and that this ob
c410: 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 ject is only use
c420: 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 ful to a tiny mi
c430: 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 nority of applic
c440: 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 ations.** with s
c450: 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 pecialized memor
c460: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
c470: 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 uirements. This
c480: 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c object is.** al
c490: 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 so used during t
c4a0: 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 esting of SQLite
c4b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 in order to spe
c4c0: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 cify an alternat
c4d0: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c ive.** memory al
c4e0: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d locator that sim
c4f0: 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 ulates memory ou
c500: 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 t-of-memory cond
c510: 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 itions in.** ord
c520: 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 er to verify tha
c530: 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 t SQLite recover
c540: 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f s gracefully fro
c550: 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 m such.** condit
c560: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ions..**.** The
c570: 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65 xMalloc and xFre
c580: 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 e methods must w
c590: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 ork like the.**
c5a0: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 malloc() and fre
c5b0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 e() functions fr
c5c0: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 om the standard
c5d0: 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 C library..** Th
c5e0: 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f e xRealloc metho
c5f0: 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 d must work like
c600: 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 realloc() from
c610: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
c620: 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20 74 ibrary.** with t
c630: 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68 61 he exception tha
c640: 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64 20 t if the second
c650: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65 61 argument to xRea
c660: 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a lloc is zero,.**
c670: 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62 xRealloc must b
c680: 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d e a no-op - it m
c690: 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20 ust not perform
c6a0: 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f any allocation o
c6b0: 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f r.** deallocatio
c6c0: 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67 75 61 72 n. ^SQLite guar
c6d0: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
c6e0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
c6f0: 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 to.** xRealloc i
c700: 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 s always a value
c710: 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 returned by a p
c720: 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f rior call to xRo
c730: 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f undup..** And so
c740: 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65 20 in cases where
c750: 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73 20 xRoundup always
c760: 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 returns a positi
c770: 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 ve number,.** xR
c780: 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f ealloc can perfo
c790: 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74 68 rm exactly as th
c7a0: 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 e standard libra
c7b0: 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 ry realloc() and
c7c0: 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e 20 .** still be in
c7d0: 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68 20 compliance with
c7e0: 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74 69 this specificati
c7f0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 on..**.** xSize
c800: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 should return th
c810: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
c820: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c of a memory all
c830: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 ocation.** previ
c840: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 ously obtained f
c850: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 rom xMalloc or x
c860: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c Realloc. The al
c870: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 located size.**
c880: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 is always at lea
c890: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 st as big as the
c8a0: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 requested size
c8b0: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 but may be large
c8c0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f r..**.** The xRo
c8d0: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 undup method ret
c8e0: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 urns what would
c8f0: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 be the allocated
c900: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 size of.** a me
c910: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
c920: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c given a particul
c930: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a ar requested siz
c940: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a e. Most memory.
c950: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f ** allocators ro
c960: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c und up memory al
c970: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 locations at lea
c980: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d st to the next m
c990: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e ultiple.** of 8.
c9a0: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 Some allocator
c9b0: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 s round up to a
c9c0: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 larger multiple
c9d0: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 or to a power of
c9e0: 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 2..** Every mem
c9f0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
ca00: 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e equest coming in
ca10: 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 through [sqlite
ca20: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 3_malloc()].** o
ca30: 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
ca40: 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c oc()] first call
ca50: 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 s xRoundup. If
ca60: 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 xRoundup returns
ca70: 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 0, .** that cau
ca80: 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f ses the correspo
ca90: 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c nding memory all
caa0: 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e ocation to fail.
cab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 .**.** The xInit
cac0: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 method initiali
cad0: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 zes the memory a
cae0: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 llocator. (For
caf0: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d example,.** it m
cb00: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e ight allocate an
cb10: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 y require mutexe
cb20: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 s or initialize
cb30: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a internal data.**
cb40: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 structures. Th
cb50: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 e xShutdown meth
cb60: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 od is invoked (i
cb70: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a ndirectly) by.**
cb80: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
cb90: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 wn()] and should
cba0: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 deallocate any
cbb0: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 resources acquir
cbc0: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 ed.** by xInit.
cbd0: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f The pAppData po
cbe0: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 inter is used as
cbf0: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
cc00: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 ter to.** xInit
cc10: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a and xShutdown..*
cc20: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 *.** SQLite hold
cc30: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
cc40: 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
cc50: 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 R] mutex when it
cc60: 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 invokes.** the
cc70: 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f xInit method, so
cc80: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
cc90: 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 d need not be th
cca0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a readsafe. The.*
ccb0: 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 * xShutdown meth
ccc0: 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 od is only calle
ccd0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
cce0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 shutdown()] so i
ccf0: 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 t does.** not ne
cd00: 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 ed to be threads
cd10: 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 afe either. For
cd20: 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f all other metho
cd30: 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f ds, SQLite.** ho
cd40: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
cd50: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
cd60: 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 ] mutex as long
cd70: 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 as the.** [SQLIT
cd80: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
cd90: 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f US] configuratio
cda0: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e n option is turn
cdb0: 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 ed on (which.**
cdc0: 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 it is by default
cdd0: 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 ) and so the met
cde0: 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 hods are automat
cdf0: 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 ically serialize
ce00: 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 d..** However, i
ce10: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
ce20: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 _MEMSTATUS] is d
ce30: 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 isabled, then th
ce40: 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f e other.** metho
ce50: 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 ds must be threa
ce60: 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 dsafe or else ma
ce70: 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 ke their own arr
ce80: 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a angements for.**
ce90: 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a serialization..
cea0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
ceb0: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 l never invoke x
cec0: 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e Init() more than
ced0: 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e once without an
cee0: 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 intervening.**
cef0: 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 call to xShutdow
cf00: 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n()..*/.typedef
cf10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
cf20: 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 em_methods sqlit
cf30: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a e3_mem_methods;.
cf40: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
cf50: 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 em_methods {. v
cf60: 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 oid *(*xMalloc)(
cf70: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a int); /*
cf80: 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
cf90: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 on function */.
cfa0: 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 void (*xFree)(v
cfb0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
cfc0: 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 /* Free a prior
cfd0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
cfe0: 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 void *(*xRealloc
cff0: 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f )(void*,int); /
d000: 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f * Resize an allo
d010: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
d020: 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b (*xSize)(void*);
d030: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 /* Re
d040: 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 turn the size of
d050: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
d060: 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 /. int (*xRound
d070: 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 up)(int);
d080: 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 /* Round up r
d090: 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 equest size to a
d0a0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a llocation size *
d0b0: 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 /. int (*xInit)
d0c0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
d0d0: 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 /* Initialize
d0e0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
d0f0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
d100: 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 (*xShutdown)(voi
d110: 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 d*); /* Dei
d120: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
d130: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
d140: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
d150: 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 ta;
d160: 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 /* Argument t
d170: 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 o xInit() and xS
d180: 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a hutdown() */.};.
d190: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
d1a0: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
d1b0: 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ptions.**.** The
d1c0: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
d1d0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 the available i
d1e0: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 nteger configura
d1f0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 tion options tha
d200: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 t.** can be pass
d210: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
d220: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
d230: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
d240: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
d250: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
d260: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
d270: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
d280: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
d290: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
d2a0: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
d2b0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
d2c0: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
d2d0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
d2e0: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
d2f0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
d300: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f from [sqlite3_co
d310: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
d320: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
d330: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 call worked. T
d340: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
d350: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ig()] interface
d360: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a will return a.**
d370: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 non-zero [error
d380: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 code] if a disc
d390: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 ontinued or unsu
d3a0: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 pported configur
d3b0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 ation option.**
d3c0: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
d3d0: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 * <dl>.** <dt>SQ
d3e0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
d3f0: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a LETHREAD</dt>.**
d400: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
d410: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
d420: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
d430: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
d440: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
d450: 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 mode] to Single
d460: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
d470: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
d480: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
d490: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 exing and puts S
d4a0: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 QLite into a mod
d4b0: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f e where it can o
d4c0: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 nly be used.** b
d4d0: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 y a single threa
d4e0: 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 d. ^If SQLite
d4f0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
d500: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
d510: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
d520: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
d530: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
d540: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
d550: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
d560: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b to change the [
d570: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
d580: 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 from its default
d590: 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e .** value of Sin
d5a0: 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 gle-thread and s
d5b0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
d5c0: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
d5d0: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 .** [SQLITE_ERR
d5e0: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 OR] if called wi
d5f0: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
d600: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
d610: 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 D.** configurati
d620: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a on option.</dd>.
d630: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
d640: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
d650: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAD</dt>.** <dd>
d660: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
d670: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
d680: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
d690: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
d6a0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
d6b0: 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 ] to Multi-threa
d6c0: 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 d. In other wor
d6d0: 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a ds, it disables.
d6e0: 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b ** mutexing on [
d6f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
d700: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ion] and [prepar
d710: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 ed statement] ob
d720: 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 jects..** The ap
d730: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 plication is res
d740: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 ponsible for ser
d750: 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 ializing access
d760: 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 to.** [database
d770: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 connections] and
d780: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
d790: 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 ments]. But oth
d7a0: 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 er mutexes.** ar
d7b0: 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 e enabled so tha
d7c0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 t SQLite will be
d7d0: 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 safe to use in
d7e0: 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 a multi-threaded
d7f0: 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 .** environment
d800: 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 as long as no tw
d810: 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 o threads attemp
d820: 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d t to use the sam
d830: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
d840: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 onnection] at th
d850: 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 e same time. ^I
d860: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
d870: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
d880: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
d890: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
d8a0: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
d8b0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
d8c0: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 hen.** it is not
d8d0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 possible to set
d8e0: 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 the Multi-threa
d8f0: 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
d900: 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 e] and.** [sqlit
d910: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
d920: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
d930: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 _ERROR] if calle
d940: 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 d with the.** SQ
d950: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
d960: 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 ITHREAD configur
d970: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
d980: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
d990: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
d9a0: 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 LIZED</dt>.** <d
d9b0: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
d9c0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
d9d0: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 option. ^This
d9e0: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
d9f0: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ** [threading mo
da00: 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 de] to Serialize
da10: 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 d. In other word
da20: 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 s, this option e
da30: 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 nables.** all mu
da40: 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 texes including
da50: 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a the recursive.**
da60: 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 mutexes on [dat
da70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
da80: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
da90: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 statement] objec
daa0: 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d ts..** In this m
dab0: 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 ode (which is th
dac0: 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 e default when S
dad0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
dae0: 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 d with.** [SQLIT
daf0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 E_THREADSAFE=1])
db00: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
db10: 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 ary will itself
db20: 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 serialize access
db30: 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 .** to [database
db40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
db50: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
db60: 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 ements] so that
db70: 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 the.** applicati
db80: 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 on is free to us
db90: 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 e the same [data
dba0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
dbb0: 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 or the.** same
dbc0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
dbd0: 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e ent] in differen
dbe0: 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 t threads at the
dbf0: 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e same time..** ^
dc00: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
dc10: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
dc20: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
dc30: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
dc40: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
dc50: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
dc60: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
dc70: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 t possible to se
dc80: 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 t the Serialized
dc90: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
dca0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
dcb0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
dcc0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
dcd0: 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
dce0: 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c with the.** SQL
dcf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
dd00: 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 LIZED configurat
dd10: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e ion option.</dd>
dd20: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
dd30: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c E_CONFIG_MALLOC<
dd40: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
dd50: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
dd60: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
dd70: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
dd80: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
dd90: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
dda0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
ddb0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
ddc0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 The argument sp
ddd0: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 ecifies.** alter
dde0: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c native low-level
ddf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
de00: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 on routines to b
de10: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 e used in place
de20: 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 of.** the memory
de30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
de40: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 ines built into
de50: 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 SQLite.)^ ^SQLit
de60: 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f e makes.** its o
de70: 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
de80: 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f of the content o
de90: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
dea0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
deb0: 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 cture.** before
dec0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
ded0: 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 fig()] call retu
dee0: 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 rns.</dd>.**.**
def0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
df00: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e G_GETMALLOC</dt>
df10: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
df20: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
df30: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
df40: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
df50: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
df60: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
df70: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
df80: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
df90: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
dfa0: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 thods].** struct
dfb0: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 ure is filled wi
dfc0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 th the currently
dfd0: 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 defined memory
dfe0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
dff0: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f nes.)^.** This o
e000: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
e010: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 d to overload th
e020: 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 e default memory
e030: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
e040: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
e050: 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 rapper that simu
e060: 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 lations memory a
e070: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 llocation failur
e080: 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d e or.** tracks m
e090: 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 emory usage, for
e0a0: 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a example. </dd>.
e0b0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
e0c0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
e0d0: 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e S</dt>.** <dd> ^
e0e0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
e0f0: 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e s single argumen
e100: 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 t of type int, i
e110: 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
e120: 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 .** boolean, whi
e130: 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ch enables or di
e140: 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 sables the colle
e150: 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 ction of memory
e160: 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 allocation .** s
e170: 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 tatistics. ^(Whe
e180: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
e190: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
e1a0: 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 re disabled, the
e1b0: 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 .** following S
e1c0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
e1d0: 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 become non-oper
e1e0: 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 ational:.** <u
e1f0: 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 l>.** <li> [sq
e200: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
e210: 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b d()].** <li> [
e220: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
e230: 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 ighwater()].**
e240: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
e250: 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 oft_heap_limit()
e260: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
e270: 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a ite3_status()].*
e280: 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e * </ul>)^.** ^
e290: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f Memory allocatio
e2a0: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 n statistics are
e2b0: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 enabled by defa
e2c0: 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 ult unless SQLit
e2d0: 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 e is.** compiled
e2e0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 with [SQLITE_DE
e2f0: 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d FAULT_MEMSTATUS]
e300: 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 =0 in which case
e310: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
e320: 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 ation statistics
e330: 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 are disabled by
e340: 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 default..** </d
e350: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
e360: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
e370: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 CH</dt>.** <dd>
e380: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 ^This option spe
e390: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
e3a0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
e3b0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 at SQLite can us
e3c0: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 e for.** scratch
e3d0: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 memory. There
e3e0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
e3f0: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 nts: A pointer
e400: 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 an 8-byte.** ali
e410: 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 gned memory buff
e420: 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 er from which th
e430: 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74 e scrach allocat
e440: 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 ions will be.**
e450: 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 drawn, the size
e460: 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 of each scratch
e470: 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c allocation (sz),
e480: 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 .** and the maxi
e490: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 mum number of sc
e4a0: 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
e4b0: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a s (N). The sz.*
e4c0: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 * argument must
e4d0: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 be a multiple of
e4e0: 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 16. The sz para
e4f0: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 meter should be
e500: 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c a few bytes.** l
e510: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 arger than the a
e520: 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 ctual scratch sp
e530: 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65 ace required due
e540: 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 to internal ove
e550: 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 rhead..** The fi
e560: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
e570: 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 t be a pointer t
e580: 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 o an 8-byte alig
e590: 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 ned buffer.** of
e5a0: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 at least sz*N b
e5b0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a ytes of memory..
e5c0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 ** ^SQLite will
e5d0: 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e use no more than
e5e0: 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 one scratch buf
e5f0: 66 65 72 20 70 65 72 20 74 68 72 65 61 64 2e 20 fer per thread.
e600: 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 So.** N should
e610: 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 be set to the ex
e620: 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e pected maximum n
e630: 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 umber of threads
e640: 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a . ^SQLite will.
e650: 2a 2a 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 ** never require
e660: 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 a scratch buffe
e670: 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 r that is more t
e680: 68 61 6e 20 36 20 74 69 6d 65 73 20 74 68 65 20 han 6 times the
e690: 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 database.** page
e6a0: 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 size. ^If SQLit
e6b0: 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 e needs needs ad
e6c0: 64 69 74 69 6f 6e 61 6c 20 73 63 72 61 74 63 68 ditional scratch
e6d0: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 0a memory beyond .
e6e0: 2a 2a 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 ** what is provi
e6f0: 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 ded by this conf
e700: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
e710: 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 , then .** [sqli
e720: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 te3_malloc()] wi
e730: 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 ll be used to ob
e740: 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 tain the memory
e750: 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a needed.</dd>.**.
e760: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
e770: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f NFIG_PAGECACHE</
e780: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
e790: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 s option specifi
e7a0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
e7b0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 ry buffer that S
e7c0: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f QLite can use fo
e7d0: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 r.** the databas
e7e0: 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 e page cache wit
e7f0: 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 h the default pa
e800: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
e810: 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 nation. .** Thi
e820: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
e830: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 should not be us
e840: 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 ed if an applica
e850: 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 tion-define page
e860: 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d .** cache implem
e870: 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 entation is load
e880: 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c ed using the SQL
e890: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
e8a0: 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 E option..** The
e8b0: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
e8c0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
e8d0: 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 ption: A pointer
e8e0: 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e to 8-byte align
e8f0: 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 ed.** memory, th
e900: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 e size of each p
e910: 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c age buffer (sz),
e920: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 and the number
e930: 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a of pages (N)..**
e940: 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 The sz argument
e950: 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 should be the s
e960: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 ize of the large
e970: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 st database page
e980: 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 .** (a power of
e990: 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 two between 512
e9a0: 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 and 32768) plus
e9b0: 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 a little extra f
e9c0: 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 or each.** page
e9d0: 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 header. ^The pa
e9e0: 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 ge header size i
e9f0: 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 s 20 to 40 bytes
ea00: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a depending on.**
ea10: 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 the host archit
ea20: 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 ecture. ^It is
ea30: 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 harmless, apart
ea40: 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 from the wasted
ea50: 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 memory,.** to ma
ea60: 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 ke sz a little t
ea70: 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 oo large. The f
ea80: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 irst.** argument
ea90: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f should point to
eaa0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f an allocation o
eab0: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
eac0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e bytes of memory.
ead0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
eae0: 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 use the memory
eaf0: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 provided by the
eb00: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
eb10: 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a o satisfy its.**
eb20: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f memory needs fo
eb30: 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 r the first N pa
eb40: 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 ges that it adds
eb50: 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 to cache. ^If
eb60: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 additional.** pa
eb70: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 ge cache memory
eb80: 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 is needed beyond
eb90: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 what is provide
eba0: 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e d by this option
ebb0: 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 , then.** SQLite
ebc0: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 goes to [sqlite
ebd0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 3_malloc()] for
ebe0: 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 the additional s
ebf0: 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a torage space..**
ec00: 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 ^The implementa
ec10: 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 6f tion might use o
ec20: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 ne or more of th
ec30: 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20 68 e N buffers to h
ec40: 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 old .** memory a
ec50: 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d ccounting inform
ec60: 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f 69 6e 74 ation. The point
ec70: 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 er in the first
ec80: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a argument must.**
ec90: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
eca0: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 n 8-byte boundar
ecb0: 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 y or subsequent
ecc0: 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
ecd0: 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e te.** will be un
ece0: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
ecf0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
ed00: 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a ONFIG_HEAP</dt>.
ed10: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
ed20: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
ed30: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 static memory b
ed40: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 uffer that SQLit
ed50: 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f e will use.** fo
ed60: 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e r all of its dyn
ed70: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f amic memory allo
ed80: 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 cation needs bey
ed90: 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 ond those provid
eda0: 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 ed.** for by [SQ
edb0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
edc0: 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 TCH] and [SQLITE
edd0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
ede0: 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 E]..** There are
edf0: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 three arguments
ee00: 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 : An 8-byte alig
ee10: 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 ned pointer to t
ee20: 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 he memory,.** th
ee30: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
ee40: 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 s in the memory
ee50: 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 buffer, and the
ee60: 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 minimum allocati
ee70: 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 on size..** ^If
ee80: 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 the first pointe
ee90: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f r (the memory po
eea0: 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 inter) is NULL,
eeb0: 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 then SQLite reve
eec0: 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 rts.** to using
eed0: 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f its default memo
eee0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 ry allocator (th
eef0: 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 e system malloc(
ef00: 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e ) implementation
ef10: 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e ),.** undoing an
ef20: 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 y prior invocati
ef30: 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f on of [SQLITE_CO
ef40: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e NFIG_MALLOC]. ^
ef50: 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 If the.** memory
ef60: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
ef70: 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 NULL and either
ef80: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
ef90: 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 EMSYS3] or.** [S
efa0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
efb0: 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 SYS5] are define
efc0: 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 d, then the alte
efd0: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a rnative memory.*
efe0: 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 * allocator is e
eff0: 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 ngaged to handle
f000: 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 all of SQLites
f010: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
f020: 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 n needs..** The
f030: 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 first pointer (t
f040: 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
f050: 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e r) must be align
f060: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a ed to an 8-byte.
f070: 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 ** boundary or s
f080: 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 ubsequent behavi
f090: 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c or of SQLite wil
f0a0: 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
f0b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
f0c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
f0d0: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EX</dt>.** <dd>
f0e0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^(This option ta
f0f0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
f100: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
f110: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
f120: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
f130: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
f140: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
f150: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ure. The argume
f160: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
f170: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
f180: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 level mutex rout
f190: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
f1a0: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 in place.** the
f1b0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 mutex routines b
f1c0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
f1d0: 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b .)^ ^SQLite mak
f1e0: 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
f1f0: 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 .** content of t
f200: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
f210: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
f220: 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 ture before the
f230: 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
f240: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 te3_config()] re
f250: 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 turns. ^If SQLit
f260: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
f270: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
f280: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
f290: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
f2a0: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
f2b0: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
f2c0: 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 the entire mutex
f2d0: 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 ing subsystem is
f2e0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
f2f0: 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 e build and henc
f300: 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 e calls to.** [s
f310: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
f320: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
f330: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f _CONFIG_MUTEX co
f340: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
f350: 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 on will.** retur
f360: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
f370: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
f380: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
f390: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
f3a0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
f3b0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
f3c0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
f3d0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
f3e0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
f3f0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
f400: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
f410: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a tructure. The.*
f420: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 * [sqlite3_mutex
f430: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
f440: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
f450: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
f460: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 tly defined mute
f470: 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a x routines.)^.**
f480: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
f490: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
f4a0: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
f4b0: 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f mutex allocatio
f4c0: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
f4d0: 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 th a wrapper use
f4e0: 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 d to track mutex
f4f0: 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f usage for perfo
f500: 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c rmance.** profil
f510: 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 ing or testing,
f520: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e for example. ^
f530: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
f540: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
f550: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
f560: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
f570: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
f580: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
f590: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 then.** the enti
f5a0: 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 re mutexing subs
f5b0: 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 ystem is omitted
f5c0: 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 from the build
f5d0: 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 and hence calls
f5e0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
f5f0: 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 onfig()] with th
f600: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
f610: 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 GETMUTEX configu
f620: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
f630: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
f640: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
f650: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
f660: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
f670: 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IDE</dt>.** <dd>
f680: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
f690: 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e akes two argumen
f6a0: 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e ts that determin
f6b0: 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a e the default.**
f6c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
f6d0: 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 on for the looka
f6e0: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f side memory allo
f6f0: 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a cator on each.**
f700: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
f710: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 ction]. The fir
f720: 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 st argument is t
f730: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
f740: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ch lookaside buf
f750: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 fer slot and the
f760: 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e second is the n
f770: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
f780: 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 s allocated to e
f790: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
f7a0: 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 nection.)^ ^(Th
f7b0: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
f7c0: 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 he.** <i>default
f7d0: 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 </i> lookaside s
f7e0: 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 ize. The [SQLITE
f7f0: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
f800: 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 IDE].** verb to
f810: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
f820: 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 ig()] can be use
f830: 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 d to change the
f840: 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e lookaside.** con
f850: 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e figuration on in
f860: 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 dividual connect
f870: 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a ions.)^ </dd>.**
f880: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
f890: 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 ONFIG_PCACHE</dt
f8a0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
f8b0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
f8c0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
f8d0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
f8e0: 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c er to.** an [sql
f8f0: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
f900: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 ods] object. Th
f910: 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 is object specif
f920: 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ies the interfac
f930: 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d e.** to a custom
f940: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c page cache impl
f950: 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e ementation.)^ ^
f960: 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
f970: 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 opy of the.** ob
f980: 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 ject and uses it
f990: 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 for page cache
f9a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
f9b0: 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ns.</dd>.**.** <
f9c0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
f9d0: 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a _GETPCACHE</dt>.
f9e0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
f9f0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
fa00: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
fa10: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
fa20: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 to an.** [sqlit
fa30: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
fa40: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 s] object. SQLi
fa50: 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 te copies of the
fa60: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 current.** page
fa70: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
fa80: 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 ation into that
fa90: 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a object.)^ </dd>.
faa0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
fab0: 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e _CONFIG_LOG</dt>
fac0: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 .** <dd> ^The SQ
fad0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
fae0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f option takes two
faf0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f arguments: a po
fb00: 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 inter to a.** fu
fb10: 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 nction with a ca
fb20: 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 ll signature of
fb30: 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e void(*)(void*,in
fb40: 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 t,const char*),
fb50: 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 .** and a pointe
fb60: 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 r to void. ^If t
fb70: 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e he function poin
fb80: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c ter is not NULL,
fb90: 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 it is.** invoke
fba0: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f d by [sqlite3_lo
fbb0: 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 g()] to process
fbc0: 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 each logging eve
fbd0: 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 nt. ^If the.**
fbe0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
fbf0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 is NULL, the [s
fc00: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e qlite3_log()] in
fc10: 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 terface becomes
fc20: 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 a no-op..** ^The
fc30: 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 void pointer th
fc40: 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 at is the second
fc50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c argument to SQL
fc60: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 ITE_CONFIG_LOG i
fc70: 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f s.** passed thro
fc80: 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 ugh as the first
fc90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
fca0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
fcb0: 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 fined logger.**
fcc0: 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 function wheneve
fcd0: 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 r that function
fce0: 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 is invoked. ^Th
fcf0: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
fd00: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 er to.** the log
fd10: 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ger function is
fd20: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 a copy of the fi
fd30: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
fd40: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
fd50: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c ng.** [sqlite3_l
fd60: 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 og()] call and i
fd70: 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 s intended to be
fd80: 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d a [result code]
fd90: 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e or an.** [exten
fda0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
fdb0: 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 . ^The third pa
fdc0: 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 rameter passed t
fdd0: 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a o the logger is.
fde0: 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 ** log message a
fdf0: 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 fter formatting
fe00: 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 via [sqlite3_snp
fe10: 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 rintf()]..** The
fe20: 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 SQLite logging
fe30: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
fe40: 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 reentrant; the
fe50: 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a logger function.
fe60: 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 ** supplied by t
fe70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
fe80: 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 ust not invoke a
fe90: 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ny SQLite interf
fea0: 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c ace..** In a mul
feb0: 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c ti-threaded appl
fec0: 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 ication, the app
fed0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
fee0: 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 logger.** funct
fef0: 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 ion must be thre
ff00: 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a adsafe. </dd>.**
ff10: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
ff20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
ff30: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
ff40: 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 1 /* nil */.#d
ff50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
ff60: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 FIG_MULTITHREAD
ff70: 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 2 /* nil */.#
ff80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
ff90: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 NFIG_SERIALIZED
ffa0: 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 3 /* nil */.
ffb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
ffc0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 ONFIG_MALLOC
ffd0: 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 4 /* sqlite
ffe0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
fff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
10000 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
10010 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 C 5 /* sqli
10020 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a te3_mem_methods*
10030 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
10040 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
10050 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f H 6 /* vo
10060 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 id*, int sz, int
10070 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 N */.#define SQ
10080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
10090 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 CACHE 7 /*
100a0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 void*, int sz, i
100b0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nt N */.#define
100c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
100d0 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f AP 8 /
100e0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 * void*, int nBy
100f0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 te, int min */.#
10100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
10110 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 NFIG_MEMSTATUS
10120 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 9 /* boolean
10130 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
10140 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 TE_CONFIG_MUTEX
10150 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 10 /* sq
10160 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
10170 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
10180 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
10190 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f TMUTEX 11 /
101a0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
101b0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 methods* */./* p
101c0 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 reviously SQLITE
101d0 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c _CONFIG_CHUNKALL
101e0 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e OC 12 which is n
101f0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 ow unused. */ .#
10200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
10210 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 NFIG_LOOKASIDE
10220 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 13 /* int int
10230 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
10240 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
10250 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 14 /* sq
10260 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
10270 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
10280 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
10290 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 ETPCACHE 15
102a0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
102b0 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 e_methods* */.#d
102c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
102d0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 FIG_LOG
102e0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 16 /* xFunc, v
102f0 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 oid* */../*.** C
10300 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
10310 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e e Connection Con
10320 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f figuration Optio
10330 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 ns.**.** These c
10340 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
10350 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
10360 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
10370 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
10380 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
10390 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
103a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
103b0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
103c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
103d0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
103e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
103f0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
10400 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
10410 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
10420 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
10430 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
10440 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
10450 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
10460 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
10470 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
10480 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 from [sqlite3_db
10490 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 _config()] to ma
104a0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 ke sure that.**
104b0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e the call worked.
104c0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ^The [sqlite3_
104d0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
104e0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
104f0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
10500 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
10510 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
10520 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
10530 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
10540 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
10550 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
10560 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
10570 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
10580 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
10590 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 s option takes t
105a0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 hree additional
105b0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
105c0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a etermine the .**
105d0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f [lookaside memo
105e0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f ry allocator] co
105f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 nfiguration for
10600 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
10610 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 nnection]..** ^T
10620 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
10630 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 t (the third par
10640 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
10650 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
10660 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 is a.** pointer
10670 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66 to an memory buf
10680 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c fer to use for l
10690 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e ookaside memory.
106a0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
106b0 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 rgument after th
106c0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
106d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 G_LOOKASIDE verb
106e0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 .** may be NULL
106f0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 in which case SQ
10700 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 Lite will alloca
10710 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 te the.** lookas
10720 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c ide buffer itsel
10730 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 f using [sqlite3
10740 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 _malloc()]. ^The
10750 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
10760 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 is the.** size
10770 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 of each lookasid
10780 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 e buffer slot.
10790 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d ^The third argum
107a0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ent is the numbe
107b0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 r of.** slots.
107c0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
107d0 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 buffer in the fi
107e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
107f0 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 t be greater tha
10800 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f n.** or equal to
10810 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 the product of
10820 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
10830 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 hird arguments.
10840 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d The buffer.** m
10850 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 ust be aligned t
10860 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e o an 8-byte boun
10870 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 dary. ^If the s
10880 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
10890 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f o.** SQLITE_DBCO
108a0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 NFIG_LOOKASIDE i
108b0 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 s not a multiple
108c0 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 of 8, it is int
108d0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 ernally.** round
108e0 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e ed down to the n
108f0 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d ext smaller.** m
10900 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 53 ultiple of 8. S
10910 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
10920 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
10930 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f E]</dd>.**.** </
10940 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
10950 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
10960 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31 OOKASIDE 1001
10970 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 /* void* int i
10980 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt */.../*.** CA
10990 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f PI3REF: Enable O
109a0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 r Disable Extend
109b0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a ed Result Codes.
109c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
109d0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
109e0 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 lt_codes() routi
109f0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ne enables or di
10a00 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 sables the.** [e
10a10 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
10a20 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 odes] feature of
10a30 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 SQLite. ^The ex
10a40 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a tended result.**
10a50 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 codes are disab
10a60 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 led by default f
10a70 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f or historical co
10a80 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a mpatibility..*/.
10a90 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
10aa0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
10ab0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
10ac0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
10ad0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e API3REF: Last In
10ae0 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a sert Rowid.**.**
10af0 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 ^Each entry in
10b00 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 an SQLite table
10b10 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d has a unique 64-
10b20 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e bit signed.** in
10b30 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 teger key called
10b40 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 the [ROWID | "r
10b50 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 owid"]. ^The row
10b60 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 id is always ava
10b70 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 ilable.** as an
10b80 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d undeclared colum
10b90 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f n named ROWID, O
10ba0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 ID, or _ROWID_ a
10bb0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a s long as those.
10bc0 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 ** names are not
10bd0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 also used by ex
10be0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
10bf0 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a d columns. ^If.*
10c00 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 * the table has
10c10 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 a column of type
10c20 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 [INTEGER PRIMAR
10c30 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 Y KEY] then that
10c40 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e column.** is an
10c50 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 other alias for
10c60 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a the rowid..**.**
10c70 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 ^This routine r
10c80 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 eturns the [rowi
10c90 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 d] of the most r
10ca0 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 ecent.** success
10cb0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 ful [INSERT] int
10cc0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 o the database f
10cd0 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 rom the [databas
10ce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
10cf0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
10d00 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20 gument. ^If no
10d10 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
10d20 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 RT]s.** have eve
10d30 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 r occurred on th
10d40 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e at database conn
10d50 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 ection, zero is
10d60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
10d70 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d ^(If an [INSERT]
10d80 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
10d90 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 trigger, then t
10da0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 he [rowid] of th
10db0 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f e inserted.** ro
10dc0 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 w is returned by
10dd0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 this routine as
10de0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 long as the tri
10df0 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e gger is running.
10e00 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 .** But once the
10e10 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 trigger termina
10e20 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 tes, the value r
10e30 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 eturned by this
10e40 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 routine.** rever
10e50 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 ts to the last v
10e60 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 alue inserted be
10e70 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 fore the trigger
10e80 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 fired.)^.**.**
10e90 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 ^An [INSERT] tha
10ea0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 t fails due to a
10eb0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
10ec0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a ation is not a.*
10ed0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e * successful [IN
10ee0 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e SERT] and does n
10ef0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
10f00 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
10f10 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e this.** routine.
10f20 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f ^Thus INSERT O
10f30 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f R FAIL, INSERT O
10f40 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 R IGNORE, INSERT
10f50 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a OR ROLLBACK,.**
10f60 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 and INSERT OR A
10f70 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 BORT make no cha
10f80 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 nges to the retu
10f90 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
10fa0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e .** routine when
10fb0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e their insertion
10fc0 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 fails. ^(When
10fd0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 INSERT OR REPLAC
10fe0 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 E.** encounters
10ff0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
11000 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 lation, it does
11010 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a not fail. The.*
11020 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 * INSERT continu
11030 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e es to completion
11040 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 after deleting
11050 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 rows that caused
11060 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 .** the constrai
11070 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e nt problem so IN
11080 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 SERT OR REPLACE
11090 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e will always chan
110a0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e ge.** the return
110b0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 value of this i
110c0 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a nterface.)^.**.*
110d0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f * ^For the purpo
110e0 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ses of this rout
110f0 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d ine, an [INSERT]
11100 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 is considered t
11110 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 o.** be successf
11120 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 ul even if it is
11130 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f subsequently ro
11140 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a lled back..**.**
11150 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
11160 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 s accessible to
11170 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 SQL statements v
11180 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f ia the.** [last_
11190 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 insert_rowid() S
111a0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
111b0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
111c0 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d e thread perform
111d0 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d s a new [INSERT]
111e0 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 on the same.**
111f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11200 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 ion while the [s
11210 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
11220 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 rt_rowid()].** f
11230 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
11240 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e ng and thus chan
11250 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 ges the last ins
11260 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 ert [rowid],.**
11270 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 then the value r
11280 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
11290 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
112a0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 rowid()] is.** u
112b0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
112c0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c might not equal
112d0 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 either the old
112e0 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 or the new.** la
112f0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 st insert [rowid
11300 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e ]..*/.sqlite3_in
11310 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 t64 sqlite3_last
11320 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 _insert_rowid(sq
11330 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
11340 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 CAPI3REF: Count
11350 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f The Number Of Ro
11360 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a ws Modified.**.*
11370 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
11380 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
11390 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 ber of database
113a0 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 rows that were c
113b0 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 hanged.** or ins
113c0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 erted or deleted
113d0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 by the most rec
113e0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 ently completed
113f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL statement.**
11400 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 on the [databas
11410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
11420 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 ecified by the f
11430 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a irst parameter..
11440 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 ** ^(Only change
11450 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 s that are direc
11460 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 tly specified by
11470 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b the [INSERT], [
11480 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b UPDATE],.** or [
11490 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e DELETE] statemen
114a0 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 t are counted.
114b0 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 Auxiliary change
114c0 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 s caused by.** t
114d0 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 riggers or [fore
114e0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d ign key actions]
114f0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
11500 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b .)^ Use the.** [
11510 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
11520 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f anges()] functio
11530 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f n to find the to
11540 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 tal number of ch
11550 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 anges.** includi
11560 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ng changes cause
11570 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e d by triggers an
11580 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 d foreign key ac
11590 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 tions..**.** ^Ch
115a0 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 anges to a view
115b0 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 that are simulat
115c0 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 ed by an [INSTEA
115d0 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a D OF trigger].**
115e0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
115f0 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 . Only real tab
11600 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 le changes are c
11610 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ounted..**.** ^(
11620 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 A "row change" i
11630 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 s a change to a
11640 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 single row of a
11650 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 single table.**
11660 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 caused by an INS
11670 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 ERT, DELETE, or
11680 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 UPDATE statement
11690 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 . Rows that.**
116a0 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 are changed as s
116b0 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b ide effects of [
116c0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 REPLACE] constra
116d0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a int resolution,.
116e0 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f ** rollback, ABO
116f0 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b RT processing, [
11700 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 DROP TABLE], or
11710 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 by any other.**
11720 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f mechanisms do no
11730 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 t count as direc
11740 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e t row changes.)^
11750 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 .**.** A "trigge
11760 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 r context" is a
11770 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 scope of executi
11780 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 on that begins a
11790 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 nd.** ends with
117a0 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 the script of a
117b0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 [CREATE TRIGGER
117c0 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 | trigger]. .**
117d0 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 Most SQL stateme
117e0 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 nts are.** evalu
117f0 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 ated outside of
11800 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 any trigger. Th
11810 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c is is the "top l
11820 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 evel".** trigger
11830 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 context. If a
11840 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 trigger fires fr
11850 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c om the top level
11860 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 , a.** new trigg
11870 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e er context is en
11880 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 tered for the du
11890 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f ration of that o
118a0 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 ne.** trigger.
118b0 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 Subtriggers crea
118c0 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 te subcontexts f
118d0 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f or their duratio
118e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e n..**.** ^Callin
118f0 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 g [sqlite3_exec(
11900 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 )] or [sqlite3_s
11910 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 tep()] recursive
11920 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 ly does.** not c
11930 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 reate a new trig
11940 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a ger context..**.
11950 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
11960 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
11970 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 mber of direct r
11980 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 ow changes in th
11990 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 e.** most recent
119a0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
119b0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
119c0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
119d0 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 same.** trigger
119e0 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e context..**.** ^
119f0 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 Thus, when calle
11a00 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c d from the top l
11a10 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 evel, this funct
11a20 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a ion returns the.
11a30 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 ** number of cha
11a40 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 nges in the most
11a50 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 recent INSERT,
11a60 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
11a70 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f E.** that also o
11a80 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 ccurred at the t
11a90 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 op level. ^(Wit
11aa0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 hin the body of
11ab0 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 a trigger,.** th
11ac0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 e sqlite3_change
11ad0 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 s() interface ca
11ae0 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 n be called to f
11af0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ind the number o
11b00 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 f.** changes in
11b10 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c the most recentl
11b20 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 y completed INSE
11b30 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
11b40 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 ELETE.** stateme
11b50 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f nt within the bo
11b60 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 dy of the same t
11b70 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 rigger..** Howev
11b80 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 er, the number r
11b90 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 eturned does not
11ba0 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 include changes
11bb0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 .** caused by su
11bc0 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 btriggers since
11bd0 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 those have their
11be0 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a own context.)^.
11bf0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 **.** See also t
11c00 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 he [sqlite3_tota
11c10 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 l_changes()] int
11c20 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b erface, the.** [
11c30 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 count_changes pr
11c40 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b agma], and the [
11c50 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 changes() SQL fu
11c60 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
11c70 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
11c80 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
11c90 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
11ca0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
11cb0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 n.** while [sqli
11cc0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 te3_changes()] i
11cd0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 s running then t
11ce0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
11cf0 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 d.** is unpredic
11d00 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 table and not me
11d10 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 aningful..*/.int
11d20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
11d30 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
11d40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 ** CAPI3REF: Tot
11d50 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 al Number Of Row
11d60 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a s Modified.**.**
11d70 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^This function
11d80 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
11d90 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 er of row change
11da0 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 s caused by [INS
11db0 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 ERT],.** [UPDATE
11dc0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 ] or [DELETE] st
11dd0 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 atements since t
11de0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
11df0 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 nection] was ope
11e00 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f ned..** ^(The co
11e10 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 unt returned by
11e20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
11e30 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 anges() includes
11e40 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 all changes.**
11e50 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 from all [CREATE
11e60 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
11e70 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 er] contexts and
11e80 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 changes made by
11e90 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 .** [foreign key
11ea0 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 actions]. Howev
11eb0 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 er,.** the count
11ec0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
11ed0 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 e changes used t
11ee0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 o implement [REP
11ef0 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 LACE] constraint
11f00 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 s,.** do rollbac
11f10 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 ks or ABORT proc
11f20 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 essing, or [DROP
11f30 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 TABLE] processi
11f40 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e ng. The.** coun
11f50 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 t does not inclu
11f60 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 de rows of views
11f70 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 that fire an [I
11f80 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
11f90 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 r],.** though if
11fa0 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 the INSTEAD OF
11fb0 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 trigger makes ch
11fc0 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e anges of its own
11fd0 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 , those changes
11fe0 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e .** are counted.
11ff0 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 )^.** ^The sqlit
12000 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
12010 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e () function coun
12020 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 ts the changes a
12030 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 s soon as.** the
12040 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
12050 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f makes them is co
12060 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 mpleted (when th
12070 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 e statement hand
12080 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 le.** is passed
12090 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
120a0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
120b0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a _finalize()])..*
120c0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
120d0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
120e0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c es()] interface,
120f0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 the.** [count_c
12100 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 hanges pragma],
12110 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 and the [total_c
12120 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
12130 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
12140 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
12150 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 ad makes changes
12160 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
12170 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
12180 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 .** while [sqlit
12190 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
121a0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
121b0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a hen the value.**
121c0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 returned is unp
121d0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
121e0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
121f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f /.int sqlite3_to
12200 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 tal_changes(sqli
12210 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
12220 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 PI3REF: Interrup
12230 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 t A Long-Running
12240 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 Query.**.** ^Th
12250 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 is function caus
12260 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 es any pending d
12270 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
12280 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a n to abort and.*
12290 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 * return at its
122a0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 earliest opportu
122b0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 nity. This routi
122c0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a ne is typically.
122d0 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 ** called in res
122e0 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 ponse to a user
122f0 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 action such as p
12300 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 ressing "Cancel"
12310 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 .** or Ctrl-C wh
12320 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e ere the user wan
12330 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 ts a long query
12340 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c operation to hal
12350 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 t.** immediately
12360 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 ..**.** ^It is s
12370 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 afe to call this
12380 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 routine from a
12390 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 thread different
123a0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 from the.** thr
123b0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 ead that is curr
123c0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 ently running th
123d0 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 e database opera
123e0 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a tion. But it.**
123f0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
12400 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e call this routin
12410 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 e with a [databa
12420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
12430 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 hat.** is closed
12440 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 or might close
12450 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 before sqlite3_i
12460 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 nterrupt() retur
12470 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ns..**.** ^If an
12480 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 SQL operation i
12490 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 s very nearly fi
124a0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 nished at the ti
124b0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 me when.** sqlit
124c0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 e3_interrupt() i
124d0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 s called, then i
124e0 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 t might not have
124f0 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a an opportunity.
12500 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 ** to be interru
12510 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 pted and might c
12520 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c ontinue to compl
12530 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e etion..**.** ^An
12540 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 SQL operation t
12550 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 hat is interrupt
12560 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b ed will return [
12570 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
12580 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e ]..** ^If the in
12590 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 terrupted SQL op
125a0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e eration is an IN
125b0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
125c0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 DELETE.** that
125d0 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 is inside an exp
125e0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
125f0 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 n, then the enti
12600 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a re transaction.*
12610 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 * will be rolled
12620 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 back automatica
12630 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 lly..**.** ^The
12640 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
12650 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 t(D) call is in
12660 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c effect until all
12670 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
12680 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d ng.** SQL statem
12690 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 ents on [databas
126a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 e connection] D
126b0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 complete. ^Any
126c0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e new SQL statemen
126d0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
126e0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
126f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
12700 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 pt() call and be
12710 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e fore the .** run
12720 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 ning statements
12730 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
12740 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 interrupted as
12750 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e if they had been
12760 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f .** running prio
12770 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
12780 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
12790 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 l. ^New SQL sta
127a0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
127b0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
127c0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 r the running st
127d0 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 atement count re
127e0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a aches zero are.*
127f0 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 * not effected b
12800 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e y the sqlite3_in
12810 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 terrupt()..** ^A
12820 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
12830 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 _interrupt(D) th
12840 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 at occurs when t
12850 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e here are no runn
12860 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
12870 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 ments is a no-op
12880 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 and has no effe
12890 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d ct on SQL statem
128a0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
128b0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
128c0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
128d0 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 rupt() call retu
128e0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 rns..**.** If th
128f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
12900 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 ction closes whi
12910 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 le [sqlite3_inte
12920 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 rrupt()].** is r
12930 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 unning then bad
12940 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 things will like
12950 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f ly happen..*/.vo
12960 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 id sqlite3_inter
12970 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a rupt(sqlite3*);.
12980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
12990 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e Determine If An
129a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 SQL Statement I
129b0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a s Complete.**.**
129c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
129d0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e are useful durin
129e0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 g command-line i
129f0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e nput to determin
12a00 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 e if the.** curr
12a10 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 ently entered te
12a20 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d xt seems to form
12a30 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
12a40 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 statement or.**
12a50 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e if additional in
12a60 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 put is needed be
12a70 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 fore sending the
12a80 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 text into.** SQ
12a90 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 Lite for parsing
12aa0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e . ^These routin
12ab0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 es return 1 if t
12ac0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a he input string.
12ad0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 ** appears to be
12ae0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
12af0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 statement. ^A s
12b00 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 tatement is judg
12b10 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ed to be.** comp
12b20 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 lete if it ends
12b30 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e with a semicolon
12b40 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f token and is no
12b50 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a t a prefix of a.
12b60 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 ** well-formed C
12b70 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 REATE TRIGGER st
12b80 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 atement. ^Semic
12b90 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 olons that are e
12ba0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a mbedded within.*
12bb0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c * string literal
12bc0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e s or quoted iden
12bd0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 tifier names or
12be0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 comments are not
12bf0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 .** independent
12c00 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 tokens (they are
12c10 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b part of the tok
12c20 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 en in which they
12c30 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 are.** embedded
12c40 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f ) and thus do no
12c50 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 t count as a sta
12c60 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f tement terminato
12c70 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a r. ^Whitespace.
12c80 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 ** and comments
12c90 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 that follow the
12ca0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 final semicolon
12cb0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a are ignored..**.
12cc0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
12cd0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 es return 0 if t
12ce0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
12cf0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 incomplete. ^If
12d00 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c a.** memory all
12d10 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 ocation fails, t
12d20 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d hen SQLITE_NOMEM
12d30 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
12d40 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
12d50 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 nes do not parse
12d60 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
12d70 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c nts thus.** will
12d80 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 not detect synt
12d90 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 actically incorr
12da0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e ect SQL..**.** ^
12db0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e (If SQLite has n
12dc0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 ot been initiali
12dd0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 zed using [sqlit
12de0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
12df0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e prior .** to in
12e00 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 voking sqlite3_c
12e10 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e omplete16() then
12e20 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
12e30 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
12e40 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
12e50 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d y by sqlite3_com
12e60 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 plete16(). If t
12e70 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 hat initializati
12e80 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 on fails,.** the
12e90 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
12ea0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
12eb0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c complete16() wil
12ec0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a l be non-zero.**
12ed0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
12ee0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
12ef0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 e input SQL is c
12f00 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a omplete.)^.**.**
12f10 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
12f20 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
12f30 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
12f40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
12f50 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a UTF-8 string..**
12f60 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f .** The input to
12f70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
12f80 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 te16()] must be
12f90 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
12fa0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
12fb0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 ng in native byt
12fc0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 e order..*/.int
12fd0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
12fe0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c (const char *sql
12ff0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
13000 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 omplete16(const
13010 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a void *sql);../*.
13020 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 ** CAPI3REF: Reg
13030 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b ister A Callback
13040 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 To Handle SQLIT
13050 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a E_BUSY Errors.**
13060 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
13070 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 e sets a callbac
13080 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 k function that
13090 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 might be invoked
130a0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 whenever.** an
130b0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 attempt is made
130c0 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 to open a databa
130d0 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e se table that an
130e0 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 other thread.**
130f0 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c or process has l
13100 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 ocked..**.** ^If
13110 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 the busy callba
13120 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e ck is NULL, then
13130 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
13140 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
13150 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 BLOCKED].** is r
13160 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 eturned immediat
13170 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 ely upon encount
13180 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 ering the lock.
13190 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 ^If the busy ca
131a0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 llback.** is not
131b0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 NULL, then the
131c0 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 callback might b
131d0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 e invoked with t
131e0 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a wo arguments..**
131f0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
13200 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 rgument to the b
13210 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 usy handler is a
13220 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 copy of the voi
13230 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 d* pointer which
13240 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 .** is the third
13250 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
13260 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
13270 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e r(). ^The secon
13280 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
13290 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
132a0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 r callback is th
132b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 e number of time
132c0 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 s that the busy
132d0 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 handler has.** b
132e0 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 een invoked for
132f0 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 this locking eve
13300 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 nt. ^If the.**
13310 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 busy callback re
13320 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f turns 0, then no
13330 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 additional atte
13340 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f mpts are made to
13350 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 .** access the d
13360 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c atabase and [SQL
13370 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 ITE_BUSY] or [SQ
13380 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
13390 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e ED] is returned.
133a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c .** ^If the call
133b0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
133c0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 -zero, then anot
133d0 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 her attempt.** i
133e0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 s made to open t
133f0 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 he database for
13400 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 reading and the
13410 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a cycle repeats..*
13420 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 *.** The presenc
13430 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 e of a busy hand
13440 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 ler does not gua
13450 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 rantee that it w
13460 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a ill be invoked.*
13470 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 * when there is
13480 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e lock contention.
13490 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 ^If SQLite dete
134a0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f rmines that invo
134b0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a king the busy.**
134c0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 handler could r
134d0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c esult in a deadl
134e0 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 ock, it will go
134f0 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e ahead and return
13500 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a [SQLITE_BUSY].*
13510 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 * or [SQLITE_IOE
13520 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 RR_BLOCKED] inst
13530 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 ead of invoking
13540 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
13550 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 ..** Consider a
13560 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f scenario where o
13570 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f ne process is ho
13580 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 lding a read loc
13590 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 k that.** it is
135a0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 trying to promot
135b0 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 e to a reserved
135c0 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 lock and.** a se
135d0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 cond process is
135e0 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 holding a reserv
135f0 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 ed lock that it
13600 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 is trying.** to
13610 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 promote to an ex
13620 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 clusive lock. T
13630 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
13640 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a cannot proceed.
13650 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 ** because it is
13660 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 blocked by the
13670 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 second and the s
13680 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 econd process ca
13690 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 nnot.** proceed
136a0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c because it is bl
136b0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 ocked by the fir
136c0 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f st. If both pro
136d0 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 cesses.** invoke
136e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
136f0 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c rs, neither will
13700 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 make any progre
13710 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a ss. Therefore,.
13720 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e ** SQLite return
13730 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 s [SQLITE_BUSY]
13740 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 for the first pr
13750 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 ocess, hoping th
13760 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 at this.** will
13770 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 induce the first
13780 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 process to rele
13790 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 ase its read loc
137a0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 k and allow.** t
137b0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 he second proces
137c0 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a s to proceed..**
137d0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 .** ^The default
137e0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 busy callback i
137f0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 s NULL..**.** ^T
13800 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d he [SQLITE_BUSY]
13810 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 error is conver
13820 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 ted to [SQLITE_I
13830 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a OERR_BLOCKED].**
13840 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
13850 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 in the middle of
13860 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 a large transac
13870 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 tion where all t
13880 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 he.** changes wi
13890 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 ll not fit into
138a0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 the in-memory ca
138b0 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c che. SQLite wil
138c0 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c l.** already hol
138d0 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 d a RESERVED loc
138e0 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 k on the databas
138f0 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e e file, but it n
13900 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f eeds.** to promo
13910 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 te this lock to
13920 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 EXCLUSIVE so tha
13930 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 t it can spill c
13940 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e ache.** pages in
13950 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
13960 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 file without har
13970 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a m to concurrent.
13980 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 ** readers. ^If
13990 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f it is unable to
139a0 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 promote the loc
139b0 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d k, then the in-m
139c0 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 emory.** cache w
139d0 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 ill be left in a
139e0 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 n inconsistent s
139f0 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 tate and so the
13a00 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 error.** code is
13a10 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 promoted from t
13a20 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 he relatively be
13a30 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 nign [SQLITE_BUS
13a40 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 Y] to.** the mor
13a50 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 e severe [SQLITE
13a60 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
13a70 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f ^This error co
13a80 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 de promotion.**
13a90 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 forces an automa
13aa0 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 tic rollback of
13ab0 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 the changes. Se
13ac0 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 e the.** <a href
13ad0 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f ="/cvstrac/wiki?
13ae0 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c p=CorruptionFoll
13af0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e owingBusyError">
13b00 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f .** CorruptionFo
13b10 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
13b20 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 </a> wiki page f
13b30 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 or a discussion
13b40 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 of why.** this i
13b50 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a s important..**.
13b60 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f ** ^(There can o
13b70 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
13b80 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 busy handler def
13b90 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a ined for each.**
13ba0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
13bb0 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 ction]. Setting
13bc0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 a new busy hand
13bd0 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a ler clears any.*
13be0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 * previously set
13bf0 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f handler.)^ ^No
13c00 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 te that calling
13c10 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
13c20 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c meout()].** will
13c30 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 also set or cle
13c40 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ar the busy hand
13c50 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 ler..**.** The b
13c60 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f usy callback sho
13c70 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 uld not take any
13c80 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d actions which m
13c90 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 odify the.** dat
13ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13cb0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
13cc0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 e busy handler.
13cd0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e Any such action
13ce0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 s.** result in u
13cf0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f ndefined behavio
13d00 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 r..** .** A busy
13d10 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f handler must no
13d20 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 t close the data
13d30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
13d40 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 ** or [prepared
13d50 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
13d60 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
13d70 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 handler..*/.int
13d80 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
13d90 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 ndler(sqlite3*,
13da0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 int(*)(void*,int
13db0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
13dc0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 * CAPI3REF: Set
13dd0 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a A Busy Timeout.*
13de0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
13df0 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 ne sets a [sqlit
13e00 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 e3_busy_handler
13e10 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 | busy handler]
13e20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 that sleeps.** f
13e30 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 or a specified a
13e40 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 mount of time wh
13e50 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f en a table is lo
13e60 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 cked. ^The hand
13e70 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 ler.** will slee
13e80 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 p multiple times
13e90 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 until at least
13ea0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 "ms" millisecond
13eb0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a s of sleeping.**
13ec0 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 have accumulate
13ed0 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 d. ^After at le
13ee0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 ast "ms" millise
13ef0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e conds of sleepin
13f00 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 g,.** the handle
13f10 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 r returns 0 whic
13f20 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 h causes [sqlite
13f30 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 3_step()] to ret
13f40 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 urn.** [SQLITE_B
13f50 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
13f60 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a IOERR_BLOCKED]..
13f70 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 **.** ^Calling t
13f80 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
13f90 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 an argument les
13fa0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
13fb0 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 to zero.** turns
13fc0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 off all busy ha
13fd0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ndlers..**.** ^(
13fe0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 There can only b
13ff0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 e a single busy
14000 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 handler for a pa
14010 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 rticular.** [dat
14020 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
14030 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 ] any any given
14040 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 moment. If anot
14050 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 her busy handler
14060 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 .** was defined
14070 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 (using [sqlite3
14080 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d _busy_handler()]
14090 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 ) prior to calli
140a0 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 ng.** this routi
140b0 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 ne, that other b
140c0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 usy handler is c
140d0 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 leared.)^.*/.int
140e0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 sqlite3_busy_ti
140f0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 meout(sqlite3*,
14100 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int ms);../*.**
14110 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e CAPI3REF: Conven
14120 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 ience Routines F
14130 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 or Running Queri
14140 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 es.**.** Definit
14150 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 ion: A <b>result
14160 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 table</b> is me
14170 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 mory data struct
14180 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 ure created by t
14190 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 he.** [sqlite3_g
141a0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 et_table()] inte
141b0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 rface. A result
141c0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 table records t
141d0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 he.** complete q
141e0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f uery results fro
141f0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 m one or more qu
14200 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eries..**.** The
14210 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 table conceptua
14220 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 lly has a number
14230 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c of rows and col
14240 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 umns. But.** th
14250 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 ese numbers are
14260 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 not part of the
14270 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 result table its
14280 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e elf. These.** n
14290 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 umbers are obtai
142a0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 ned separately.
142b0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 Let N be the nu
142c0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 mber of rows.**
142d0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d and M be the num
142e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a ber of columns..
142f0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
14300 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 able is an array
14310 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 of pointers to
14320 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
14330 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a UTF-8 strings..*
14340 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 * There are (N+1
14350 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 )*M elements in
14360 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 the array. The
14370 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 first M pointers
14380 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 point.** to zer
14390 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
143a0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 ings that conta
143b0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 in the names of
143c0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 the columns..**
143d0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e The remaining en
143e0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 tries all point
143f0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 to query results
14400 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 . NULL values r
14410 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c esult.** in NULL
14420 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 pointers. All
14430 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 other values are
14440 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 in their UTF-8
14450 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
14460 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 ** string repres
14470 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 entation as retu
14480 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
14490 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e _column_text()].
144a0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 .**.** A result
144b0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 table might cons
144c0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f ist of one or mo
144d0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 re memory alloca
144e0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 tions..** It is
144f0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 not safe to pass
14500 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 a result table
14510 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c directly to [sql
14520 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
14530 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
14540 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f should be deallo
14550 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c cated using [sql
14560 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
14570 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 )]..**.** As an
14580 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 example of the r
14590 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d esult table form
145a0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 at, suppose a qu
145b0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ery result.** is
145c0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
145d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
145e0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e pre>.** N
145f0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 ame | Age
14600 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d .** -----
14610 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
14620 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 --.** Ali
14630 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a ce | 43.**
14640 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 Bob
14650 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 | 28.**
14660 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c Cindy |
14670 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 21.** </pre></b
14680 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
14690 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 There are two c
146a0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 olumn (M==2) and
146b0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d three rows (N==
146c0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 3). Thus the.**
146d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 result table ha
146e0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 s 8 entries. Su
146f0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 ppose the result
14700 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 table is stored
14710 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 .** in an array
14720 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 names azResult.
14730 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 Then azResult h
14740 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e olds this conten
14750 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 t:.**.** <blockq
14760 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
14770 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
14780 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 1;0] = "Name";.*
14790 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
147a0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 t[1] = "Age"
147b0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
147c0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 sult[2] = "A
147d0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 lice";.**
147e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d azResult[3]
147f0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 = "43";.**
14800 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
14810 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 4] = "Bob";.**
14820 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
14830 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 91;5] = "28";.**
14840 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
14850 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 [6] = "Cindy
14860 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
14870 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 esult[7] = "
14880 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 21";.** </pre></
14890 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
148a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 * ^The sqlite3_g
148b0 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 et_table() funct
148c0 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e ion evaluates on
148d0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d e or more.** sem
148e0 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 icolon-separated
148f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
14900 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d in the zero-term
14910 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 inated UTF-8.**
14920 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e string of its 2n
14930 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 d parameter and
14940 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 returns a result
14950 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a table to the.**
14960 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 pointer given i
14970 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 n its 3rd parame
14980 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 ter..**.** After
14990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
149a0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
149b0 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 th the result fr
149c0 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 om sqlite3_get_t
149d0 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 73 68 able(),.** it sh
149e0 6f 75 6c 64 20 70 61 73 73 20 74 68 65 20 72 65 ould pass the re
149f0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 sult table point
14a00 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 er to sqlite3_fr
14a10 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 ee_table() in or
14a20 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 der to.** releas
14a30 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 e the memory tha
14a40 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 t was malloced.
14a50 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
14a60 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 way the.** [sqli
14a70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 te3_malloc()] ha
14a80 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c ppens within sql
14a90 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
14aa0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a , the calling.**
14ab0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e function must n
14ac0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b ot try to call [
14ad0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
14ae0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a directly. Only.
14af0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
14b00 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c _table()] is abl
14b10 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 e to release the
14b20 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 memory properly
14b30 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a and safely..**.
14b40 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
14b50 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 _get_table() int
14b60 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d erface is implem
14b70 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 ented as a wrapp
14b80 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 er around.** [sq
14b90 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 lite3_exec()].
14ba0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
14bb0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 table() routine
14bc0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 does not have ac
14bd0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 cess.** to any i
14be0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 nternal data str
14bf0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 uctures of SQLit
14c00 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 e. It uses only
14c10 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 the public.** i
14c20 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 nterface defined
14c30 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e here. As a con
14c40 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 sequence, errors
14c50 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 that occur in t
14c60 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 he.** wrapper la
14c70 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 yer outside of t
14c80 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c he internal [sql
14c90 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c ite3_exec()] cal
14ca0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 l are not.** ref
14cb0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 lected in subseq
14cc0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
14cd0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
14ce0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
14cf0 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a 2f _errmsg()].)^.*/
14d00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 .int sqlite3_get
14d10 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 _table(. sqlite
14d20 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
14d30 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
14d40 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
14d50 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f har *zSql, /
14d60 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c * SQL to be eval
14d70 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 uated */. char
14d80 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 ***pazResult,
14d90 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 /* Results of t
14da0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e he query */. in
14db0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 t *pnRow,
14dc0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
14dd0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 result rows wri
14de0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 tten here */. i
14df0 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 nt *pnColumn,
14e00 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
14e10 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 f result columns
14e20 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
14e30 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d . char **pzErrm
14e40 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f sg /* Erro
14e50 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
14e60 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 re */.);.void sq
14e70 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
14e80 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b (char **result);
14e90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
14ea0 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 : Formatted Stri
14eb0 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 ng Printing Func
14ec0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
14ed0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 e routines are w
14ee0 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 ork-alikes of th
14ef0 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d e "printf()" fam
14f00 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 ily of functions
14f10 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 .** from the sta
14f20 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
14f30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
14f40 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e te3_mprintf() an
14f50 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e d sqlite3_vmprin
14f60 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 tf() routines wr
14f70 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 ite their.** res
14f80 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 ults into memory
14f90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
14fa0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14fb0 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 ]..** The string
14fc0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
14fd0 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 ese two routines
14fe0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 should be.** re
14ff0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 leased by [sqlit
15000 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f e3_free()]. ^Bo
15010 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 th routines retu
15020 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 rn a.** NULL poi
15030 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 nter if [sqlite3
15040 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e _malloc()] is un
15050 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
15060 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 enough.** memor
15070 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 y to hold the re
15080 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a sulting string..
15090 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 **.** ^(In sqlit
150a0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f e3_snprintf() ro
150b0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 utine is similar
150c0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 to "snprintf()"
150d0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 from.** the sta
150e0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
150f0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 The result is
15100 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
15110 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c .** buffer suppl
15120 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e ied as the secon
15130 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 d parameter whos
15140 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 e size is given
15150 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 by.** the first
15160 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 parameter. Note
15170 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f that the order o
15180 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 f the.** first t
15190 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 wo parameters is
151a0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 reversed from s
151b0 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 nprintf().)^ Th
151c0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 is is an.** hist
151d0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 orical accident
151e0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 that cannot be f
151f0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 ixed without bre
15200 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 aking.** backwar
15210 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
15220 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 . ^(Note also t
15230 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 hat sqlite3_snpr
15240 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e intf().** return
15250 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 s a pointer to i
15260 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 ts buffer instea
15270 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 d of the number
15280 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 of.** characters
15290 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 actually writte
152a0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 n into the buffe
152b0 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 r.)^ We admit t
152c0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 hat.** the numbe
152d0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 r of characters
152e0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 written would be
152f0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 a more useful r
15300 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 eturn.** value b
15310 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 ut we cannot cha
15320 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e nge the implemen
15330 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 tation of sqlite
15340 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
15350 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 now without brea
15360 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 king compatibili
15370 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f ty..**.** ^As lo
15380 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 ng as the buffer
15390 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 size is greater
153a0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 than zero, sqli
153b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
153c0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 * guarantees tha
153d0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 t the buffer is
153e0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d always zero-term
153f0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 inated. ^The fi
15400 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
15410 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 "n" is the tota
15420 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 l size of the bu
15430 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 ffer, including
15440 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 space for.** the
15450 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
15460 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 . So the longes
15470 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 t string that ca
15480 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a n be completely.
15490 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 ** written will
154a0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 be n-1 character
154b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s..**.** These r
154c0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c outines all impl
154d0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 ement some addit
154e0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 ional formatting
154f0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 .** options that
15500 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 are useful for
15510 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c constructing SQL
15520 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
15530 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c All of the usual
15540 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 printf() format
15550 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 ting options app
15560 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e ly. In addition
15570 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 , there.** is ar
15580 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e e "%q", "%Q", an
15590 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a d "%z" options..
155a0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f **.** ^(The %q o
155b0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
155c0 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 %s in that it s
155d0 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c ubstitutes a nul
155e0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 l-terminated.**
155f0 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 string from the
15600 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 argument list.
15610 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 But %q also doub
15620 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 les every '\'' c
15630 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 haracter..** %q
15640 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 is designed for
15650 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 use inside a str
15660 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 ing literal.)^
15670 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 By doubling each
15680 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 '\''.** charact
15690 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 er it escapes th
156a0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 at character and
156b0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 allows it to be
156c0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a inserted into.*
156d0 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a * the string..**
156e0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c .** For example,
156f0 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 assume the stri
15700 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 ng variable zTex
15710 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 t contains text
15720 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
15730 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
15740 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 re>.** char *zT
15750 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 ext = "It's a ha
15760 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f ppy day!";.** </
15770 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
15780 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 >.**.** One can
15790 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e use this text in
157a0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
157b0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
157c0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
157d0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
157e0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
157f0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
15800 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
15810 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b ('%q')", zText);
15820 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
15830 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
15840 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
15850 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
15860 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
15870 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 ote>.**.** Becau
15880 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 se the %q format
15890 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c string is used,
158a0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 the '\'' charac
158b0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 ter in zText.**
158c0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 is escaped and t
158d0 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 he SQL generated
158e0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a is as follows:.
158f0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
15900 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
15910 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
15920 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 ALUES('It''s a h
15930 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c appy day!').** <
15940 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
15950 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 e>.**.** This is
15960 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 correct. Had w
15970 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 e used %s instea
15980 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e d of %q, the gen
15990 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f erated SQL.** wo
159a0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 uld have looked
159b0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
159c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
159d0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e e>.** INSERT IN
159e0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 TO table1 VALUES
159f0 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 ('It's a happy d
15a00 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ay!');.** </pre>
15a10 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
15a20 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 .** This second
15a30 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 example is an SQ
15a40 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 L syntax error.
15a50 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 As a general ru
15a60 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a le you should.**
15a70 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 always use %q i
15a80 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 nstead of %s whe
15a90 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 n inserting text
15aa0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c into a string l
15ab0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 iteral..**.** ^(
15ac0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f The %Q option wo
15ad0 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 rks like %q exce
15ae0 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 pt it also adds
15af0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 single quotes ar
15b00 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 ound.** the outs
15b10 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c ide of the total
15b20 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 string. Additi
15b30 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 onally, if the p
15b40 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a arameter in the.
15b50 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 ** argument list
15b60 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
15b70 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 er, %Q substitut
15b80 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c es the text "NUL
15b90 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 L" (without.** s
15ba0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e ingle quotes).)^
15bb0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c So, for exampl
15bc0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 e, one could say
15bd0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
15be0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
15bf0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 ar *zSQL = sqlit
15c00 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 e3_mprintf("INSE
15c10 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 RT INTO table VA
15c20 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 LUES(%Q)", zText
15c30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 );.** sqlite3_e
15c40 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c xec(db, zSQL, 0,
15c50 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 0, 0);.** sqli
15c60 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a te3_free(zSQL);.
15c70 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
15c80 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
15c90 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c code above will
15ca0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 render a correc
15cb0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 t SQL statement
15cc0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 in the zSQL.** v
15cd0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 ariable even if
15ce0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 the zText variab
15cf0 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 le is a NULL poi
15d00 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 nter..**.** ^(Th
15d10 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e e "%z" formattin
15d20 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c g option works l
15d30 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 ike "%s" but wit
15d40 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f h the.** additio
15d50 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 n that after the
15d60 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e string has been
15d70 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 read and copied
15d80 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 into.** the res
15d90 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 ult, [sqlite3_fr
15da0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 ee()] is called
15db0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 on the input str
15dc0 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a ing.)^.*/.char *
15dd0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
15de0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 const char*,...)
15df0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f ;.char *sqlite3_
15e00 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 vmprintf(const c
15e10 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
15e20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e char *sqlite3_sn
15e30 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a printf(int,char*
15e40 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e ,const char*, ..
15e50 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
15e60 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
15e70 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d cation Subsystem
15e80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 .**.** The SQLit
15e90 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 e core uses thes
15ea0 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 e three routines
15eb0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
15ec0 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 own.** internal
15ed0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
15ee0 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 n needs. "Core"
15ef0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
15f00 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 sentence.** does
15f10 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 not include ope
15f20 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
15f30 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 ecific VFS imple
15f40 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a mentation. The.
15f50 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 ** Windows VFS u
15f60 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f ses native mallo
15f70 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
15f80 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f or some operatio
15f90 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
15fa0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
15fb0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
15fc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 a pointer to a b
15fd0 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 lock.** of memor
15fe0 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 y at least N byt
15ff0 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 es in length, wh
16000 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 ere N is the par
16010 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 ameter..** ^If s
16020 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
16030 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 is unable to obt
16040 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 ain sufficient f
16050 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 ree.** memory, i
16060 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c t returns a NULL
16070 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 pointer. ^If t
16080 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 he parameter N t
16090 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c o.** sqlite3_mal
160a0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 loc() is zero or
160b0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 negative then s
160c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
160d0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c returns.** a NUL
160e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
160f0 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 ^Calling sqlite
16100 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 3_free() with a
16110 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 pointer previous
16120 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ly returned.** b
16130 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
16140 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
16150 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 alloc() releases
16160 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a that memory so.
16170 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 ** that it might
16180 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 be reused. ^Th
16190 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 e sqlite3_free()
161a0 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 routine is.** a
161b0 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c no-op if is cal
161c0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 led with a NULL
161d0 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e pointer. Passin
161e0 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 g a NULL pointer
161f0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 .** to sqlite3_f
16200 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 ree() is harmles
16210 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 s. After being
16220 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a freed, memory.**
16230 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 should neither
16240 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 be read nor writ
16250 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 ten. Even readi
16260 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 ng previously fr
16270 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 eed.** memory mi
16280 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 ght result in a
16290 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 segmentation fau
162a0 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 lt or other seve
162b0 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d re error..** Mem
162c0 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 ory corruption,
162d0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 a segmentation f
162e0 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 ault, or other s
162f0 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d evere error.** m
16300 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 ight result if s
16310 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
16320 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e called with a n
16330 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 on-NULL pointer
16340 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 that.** was not
16350 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 obtained from sq
16360 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
16370 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
16380 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 c()..**.** ^(The
16390 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
163a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
163b0 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 empts to resize
163c0 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 a.** prior memor
163d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
163e0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 be at least N by
163f0 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 tes, where N is
16400 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 the.** second pa
16410 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 rameter. The me
16420 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
16430 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 to be resized is
16440 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 the first.** pa
16450 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 rameter.)^ ^ If
16460 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
16470 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
16480 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 ealloc().** is a
16490 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
164a0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 en its behavior
164b0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 is identical to
164c0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 calling.** sqlit
164d0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 e3_malloc(N) whe
164e0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f re N is the seco
164f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
16500 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
16510 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 )..** ^If the se
16520 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
16530 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
16540 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a c() is zero or.*
16550 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 * negative then
16560 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
16570 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 exactly the same
16580 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 as calling.** s
16590 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 qlite3_free(P) w
165a0 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 here P is the fi
165b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
165c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
165d0 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f ()..** ^sqlite3_
165e0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e realloc() return
165f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
16600 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
16610 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 on.** of at leas
16620 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a t N bytes in siz
16630 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 e or NULL if suf
16640 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 ficient memory i
16650 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a s unavailable..*
16660 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 * ^If M is the s
16670 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 ize of the prior
16680 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 allocation, the
16690 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 n min(N,M) bytes
166a0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 .** of the prior
166b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 allocation are
166c0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 copied into the
166d0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 beginning of buf
166e0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 fer returned.**
166f0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c by sqlite3_reall
16700 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 oc() and the pri
16710 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 or allocation is
16720 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 freed..** ^If s
16730 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
16740 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 returns NULL, t
16750 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c hen the prior al
16760 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e location.** is n
16770 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 ot freed..**.**
16780 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 ^The memory retu
16790 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
167a0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c malloc() and sql
167b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a ite3_realloc().*
167c0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 * is always alig
167d0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 ned to at least
167e0 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 an 8 byte bounda
167f0 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c ry..**.** In SQL
16800 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
16810 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 0 and 3.5.1, it
16820 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 was possible to
16830 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 define.** the SQ
16840 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 LITE_OMIT_MEMORY
16850 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 _ALLOCATION whic
16860 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 h would cause th
16870 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d e built-in.** im
16880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
16890 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 these routines t
168a0 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 o be omitted. T
168b0 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a hat capability.*
168c0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 * is no longer p
168d0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 rovided. Only b
168e0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
168f0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 llocators can be
16900 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 used..**.** The
16910 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 Windows OS inte
16920 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c rface layer call
16930 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 s.** the system
16940 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 malloc() and fre
16950 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 e() directly whe
16960 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 n converting.**
16970 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 filenames betwee
16980 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f n the UTF-8 enco
16990 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c ding used by SQL
169a0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 ite.** and whate
169b0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 ver filename enc
169c0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 oding is used by
169d0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 the particular
169e0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 Windows.** insta
169f0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 llation. Memory
16a00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
16a10 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c rs are detected,
16a20 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 but.** they are
16a30 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 reported back a
16a40 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 s [SQLITE_CANTOP
16a50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 EN] or.** [SQLIT
16a60 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 E_IOERR] rather
16a70 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d than [SQLITE_NOM
16a80 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 EM]..**.** The p
16a90 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 ointer arguments
16aa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 to [sqlite3_fre
16ab0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
16ac0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
16ad0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e must be either N
16ae0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e ULL or else poin
16af0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 ters obtained fr
16b00 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e om a prior.** in
16b10 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
16b20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f ite3_malloc()] o
16b30 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
16b40 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a oc()] that have.
16b50 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 ** not yet been
16b60 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 released..**.**
16b70 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
16b80 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 must not read or
16b90 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 write any part
16ba0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 of.** a block of
16bb0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 memory after it
16bc0 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 has been releas
16bd0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c ed using.** [sql
16be0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 ite3_free()] or
16bf0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
16c00 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ()]..*/.void *sq
16c10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 lite3_malloc(int
16c20 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 );.void *sqlite3
16c30 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 _realloc(void*,
16c40 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
16c50 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a e3_free(void*);.
16c60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
16c70 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f Memory Allocato
16c80 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a r Statistics.**.
16c90 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 ** SQLite provid
16ca0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 es these two int
16cb0 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f erfaces for repo
16cc0 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 rting on the sta
16cd0 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 tus.** of the [s
16ce0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
16cf0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
16d00 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
16d10 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 _realloc()].** r
16d20 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 outines, which f
16d30 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e orm the built-in
16d40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
16d50 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a on subsystem..**
16d60 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
16d70 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
16d80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
16d90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
16da0 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 ytes.** of memor
16db0 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 y currently outs
16dc0 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 tanding (malloce
16dd0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 d but not freed)
16de0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 ..** ^The [sqlit
16df0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
16e00 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 ter()] routine r
16e10 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d eturns the maxim
16e20 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b um.** value of [
16e30 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
16e40 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 sed()] since the
16e50 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b high-water mark
16e60 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 .** was last res
16e70 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 et. ^The values
16e80 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
16e90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
16ea0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c d()] and.** [sql
16eb0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
16ec0 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 water()] include
16ed0 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a any overhead.**
16ee0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 added by SQLite
16ef0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e in its implemen
16f00 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 tation of [sqlit
16f10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a e3_malloc()],.**
16f20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 but not overhea
16f30 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 d added by the a
16f40 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 ny underlying sy
16f50 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 stem library.**
16f60 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 routines that [s
16f70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
16f80 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a may call..**.**
16f90 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 ^The memory hig
16fa0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 h-water mark is
16fb0 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 reset to the cur
16fc0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a rent value of.**
16fd0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
16fe0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 _used()] if and
16ff0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 only if the para
17000 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c meter to.** [sql
17010 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
17020 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 water()] is true
17030 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 . ^The value re
17040 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 turned.** by [sq
17050 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
17060 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 hwater(1)] is th
17070 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 e high-water mar
17080 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 k.** prior to th
17090 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 e reset..*/.sqli
170a0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
170b0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 3_memory_used(vo
170c0 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 id);.sqlite3_int
170d0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 64 sqlite3_memor
170e0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 y_highwater(int
170f0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a resetFlag);../*.
17100 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 ** CAPI3REF: Pse
17110 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 udo-Random Numbe
17120 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a r Generator.**.*
17130 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e * SQLite contain
17140 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 s a high-quality
17150 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e pseudo-random n
17160 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 umber generator
17170 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a (PRNG) used to.*
17180 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 * select random
17190 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d [ROWID | ROWIDs]
171a0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 when inserting
171b0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f new records into
171c0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a a table that.**
171d0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 already uses th
171e0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 e largest possib
171f0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 le [ROWID]. The
17200 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 PRNG is also us
17210 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 ed for.** the bu
17220 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 ild-in random()
17230 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 and randomblob()
17240 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 SQL functions.
17250 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
17260 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 allows.** applic
17270 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 ations to access
17280 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 the same PRNG f
17290 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 or other purpose
172a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c s..**.** ^A call
172b0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
172c0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 stores N bytes
172d0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e of randomness in
172e0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a to buffer P..**.
172f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 ** ^The first ti
17300 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 me this routine
17310 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 is invoked (eith
17320 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 er internally or
17330 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 by.** the appli
17340 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 cation) the PRNG
17350 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 is seeded using
17360 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 randomness obta
17370 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 ined.** from the
17380 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 xRandomness met
17390 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 hod of the defau
173a0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
173b0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 object..** ^On
173c0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 all subsequent i
173d0 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 nvocations, the
173e0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 pseudo-randomnes
173f0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a s is generated.*
17400 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 * internally and
17410 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 without recours
17420 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 e to the [sqlite
17430 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 3_vfs] xRandomne
17440 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f ss.** method..*/
17450 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 .void sqlite3_ra
17460 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 ndomness(int N,
17470 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a void *P);../*.**
17480 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
17490 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a le-Time Authoriz
174a0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a ation Callbacks.
174b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
174c0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ine registers a
174d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
174e0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 ack with a parti
174f0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
17500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 se connection],
17510 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 supplied in the
17520 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
17530 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a ** ^The authoriz
17540 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
17550 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 nvoked as SQL st
17560 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 atements are bei
17570 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 ng compiled.** b
17580 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
17590 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
175a0 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 iants [sqlite3_p
175b0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a repare_v2()],.**
175c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
175d0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 e16()] and [sqli
175e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
175f0 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 ()]. ^At variou
17600 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 s.** points duri
17610 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 ng the compilati
17620 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c on process, as l
17630 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 ogic is being cr
17640 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 eated.** to perf
17650 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 orm various acti
17660 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 ons, the authori
17670 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
17680 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 invoked to.** se
17690 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f e if those actio
176a0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 ns are allowed.
176b0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 ^The authorizer
176c0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
176d0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
176e0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 TE_OK] to allow
176f0 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c the action, [SQL
17700 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 ITE_IGNORE] to d
17710 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 isallow the.** s
17720 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 pecific action b
17730 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c ut allow the SQL
17740 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f statement to co
17750 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 ntinue to be.**
17760 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 compiled, or [SQ
17770 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 LITE_DENY] to ca
17780 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 use the entire S
17790 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 QL statement to
177a0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 be.** rejected w
177b0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e ith an error. ^
177c0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 If the authorize
177d0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 r callback retur
177e0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 ns.** any value
177f0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
17800 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c TE_IGNORE], [SQL
17810 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c ITE_OK], or [SQL
17820 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 ITE_DENY].** the
17830 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 n the [sqlite3_p
17840 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
17850 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 equivalent call
17860 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a that triggered.*
17870 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
17880 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 will fail with
17890 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
178a0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
178b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
178c0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
178d0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 hat means the op
178e0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 eration.** reque
178f0 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 sted is ok. ^Wh
17900 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
17910 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
17920 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 DENY], the.** [s
17930 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
17940 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 2()] or equivale
17950 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 nt call that tri
17960 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 ggered the.** au
17970 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 thorizer will fa
17980 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 il with an error
17990 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e message explain
179a0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 ing that.** acce
179b0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a ss is denied. .*
179c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
179d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
179e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
179f0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f back is a copy o
17a00 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 f the third.** p
17a10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
17a20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
17a30 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 orizer() interfa
17a40 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 ce. ^The second
17a50 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
17a60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
17a70 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 an integer [SQLI
17a80 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e TE_COPY | action
17a90 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 code] that spec
17aa0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 ifies.** the par
17ab0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 ticular action t
17ac0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e o be authorized.
17ad0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f ^The third thro
17ae0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 ugh sixth parame
17af0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 ters.** to the c
17b00 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f allback are zero
17b10 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
17b20 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ngs that contain
17b30 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 additional.** d
17b40 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 etails about the
17b50 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
17b60 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 thorized..**.**
17b70 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 ^If the action c
17b80 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 ode is [SQLITE_R
17b90 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 EAD].** and the
17ba0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
17bb0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
17bc0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 then the.** [pr
17bd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
17be0 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 ] statement is c
17bf0 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 onstructed to su
17c00 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 bstitute.** a NU
17c10 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 LL value in plac
17c20 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 e of the table c
17c30 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 olumn that would
17c40 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 have.** been re
17c50 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b ad if [SQLITE_OK
17c60 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 ] had been retur
17c70 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ned. The [SQLIT
17c80 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 E_IGNORE].** ret
17c90 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 urn can be used
17ca0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 to deny an untru
17cb0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 sted user access
17cc0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a to individual.*
17cd0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 * columns of a t
17ce0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 able..** ^If the
17cf0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
17d00 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 [SQLITE_DELETE]
17d10 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
17d20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
17d30 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
17d40 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 the [DELETE] op
17d50 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 eration proceeds
17d60 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 but the.** [tru
17d70 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 ncate optimizati
17d80 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 on] is disabled
17d90 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 and all rows are
17da0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 deleted individ
17db0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 ually..**.** An
17dc0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 authorizer is us
17dd0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
17de0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
17df0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 ring].** SQL sta
17e00 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
17e10 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
17e20 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
17e30 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
17e40 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 nts.** do not tr
17e50 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
17e60 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
17e70 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
17e80 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
17e90 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 t.** try to exec
17ea0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
17eb0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
17ec0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
17ed0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
17ee0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
17ef0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
17f00 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
17f10 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
17f20 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
17f30 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
17f40 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
17f50 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
17f60 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
17f70 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
17f80 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
17f90 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
17fa0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
17fb0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
17fc0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
17fd0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
17fe0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
17ff0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 SQL is being [sq
18000 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
18010 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a prepared] that.*
18020 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 * disallows ever
18030 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 ything except [S
18040 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
18050 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 s..**.** Applica
18060 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 tions that need
18070 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 to process SQL f
18080 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f rom untrusted so
18090 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 urces.** might a
180a0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 lso consider low
180b0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c ering resource l
180c0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c imits using [sql
180d0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
180e0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 and limiting da
180f0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e tabase size usin
18100 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f g the [max_page_
18110 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a count] [PRAGMA].
18120 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** in addition t
18130 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f o using an autho
18140 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f rizer..**.** ^(O
18150 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 nly a single aut
18160 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 horizer can be i
18170 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 n place on a dat
18180 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18190 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 .** at a time.
181a0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c Each call to sql
181b0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
181c0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 zer overrides th
181d0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 e.** previous ca
181e0 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 ll.)^ ^Disable
181f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 the authorizer b
18200 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e y installing a N
18210 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ULL callback..**
18220 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
18230 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 is disabled by d
18240 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 efault..**.** Th
18250 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
18260 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
18270 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
18280 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
18290 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
182a0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
182b0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a ked the authoriz
182c0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 er callback..**
182d0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
182e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
182f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
18300 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
18310 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
18320 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
18330 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
18340 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
18350 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
18360 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 *.** ^When [sqli
18370 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
18380 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 ] is used to pre
18390 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
183a0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 , the.** stateme
183b0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 nt might be re-p
183c0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b repared during [
183d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
183e0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 due to a .** sch
183f0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e ema change. Hen
18400 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ce, the applicat
18410 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 ion should ensur
18420 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f e that the.** co
18430 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 rrect authorizer
18440 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e callback remain
18450 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e s in place durin
18460 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 g the [sqlite3_s
18470 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e tep()]..**.** ^N
18480 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 ote that the aut
18490 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
184a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 is invoked only
184b0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 during.** [sqli
184c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
184d0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 r its variants.
184e0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 Authorization i
184f0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d s not.** perform
18500 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d ed during statem
18510 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 ent evaluation i
18520 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 n [sqlite3_step(
18530 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 )], unless.** as
18540 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 stated in the p
18550 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
18560 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 h, sqlite3_step(
18570 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c ) invokes.** sql
18580 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
18590 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 ) to reprepare a
185a0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
185b0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
185c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
185d0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
185e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 . sqlite3*,. i
185f0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 nt (*xAuth)(void
18600 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
18610 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
18620 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
18630 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a char*),. void *
18640 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a pUserData.);../*
18650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
18660 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 thorizer Return
18670 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Codes.**.** The
18680 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
18690 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
186a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 izer callback fu
186b0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 nction] must.**
186c0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 return either [S
186d0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 QLITE_OK] or one
186e0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f of these two co
186f0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 nstants in order
18700 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 .** to signal SQ
18710 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 Lite whether or
18720 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 not the action i
18730 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 s permitted. Se
18740 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 e the.** [sqlite
18750 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
18760 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f | authorizer do
18770 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
18780 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
18790 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 nformation..*/.#
187a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
187b0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 NY 1 /* Abor
187c0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
187d0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f ent with an erro
187e0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
187f0 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f ITE_IGNORE 2 /
18800 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 * Don't allow ac
18810 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 cess, but don't
18820 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f generate an erro
18830 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 r */../*.** CAPI
18840 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 3REF: Authorizer
18850 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a Action Codes.**
18860 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
18870 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
18880 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 )] interface reg
18890 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
188a0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 k function.** th
188b0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f at is invoked to
188c0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 authorize certa
188d0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 in SQL statement
188e0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a actions. The.*
188f0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
18900 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 er to the callba
18910 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
18920 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 code that speci
18930 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 fies.** what act
18940 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 ion is being aut
18950 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 horized. These
18960 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 are the integer
18970 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 action codes tha
18980 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 t.** the authori
18990 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 zer callback may
189a0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a be passed..**.*
189b0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 * These action c
189c0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 ode values signi
189d0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 fy what kind of
189e0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 operation is to
189f0 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 be.** authorized
18a00 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 . The 3rd and 4
18a10 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
18a20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 the authorizati
18a30 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 on.** callback f
18a40 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 unction will be
18a50 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 parameters or NU
18a60 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 LL depending on
18a70 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a which of these.*
18a80 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 * codes is used
18a90 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
18aa0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 rameter. ^(The
18ab0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
18ac0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
18ad0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 er callback is t
18ae0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
18af0 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c atabase ("main",
18b00 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e "temp",.** etc.
18b10 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e ) if applicable.
18b20 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 )^ ^The 6th par
18b30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
18b40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
18b50 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 k.** is the name
18b60 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f of the inner-mo
18b70 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 st trigger or vi
18b80 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f ew that is respo
18b90 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 nsible for.** th
18ba0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 e access attempt
18bb0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 or NULL if this
18bc0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
18bd0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d is directly from
18be0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 .** top-level SQ
18bf0 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a L code..*/./****
18c00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
18c10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
18c20 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a ******* 3rd ****
18c30 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a ******** 4th ***
18c40 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e ********/.#defin
18c50 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
18c60 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 INDEX 1
18c70 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
18c80 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
18c90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
18ca0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
18cb0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 ABLE 2
18cc0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
18cd0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
18ce0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
18cf0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
18d00 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 MP_INDEX 3
18d10 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
18d20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
18d30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
18d40 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
18d50 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 P_TABLE 4
18d60 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
18d70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
18d80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
18d90 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
18da0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f _TRIGGER 5 /
18db0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
18dc0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
18dd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
18de0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
18df0 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a VIEW 6 /*
18e00 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
18e10 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
18e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18e30 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 TE_CREATE_TRIGGE
18e40 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 R 7 /*
18e50 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
18e60 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
18e70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18e80 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 E_CREATE_VIEW
18e90 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 8 /* V
18ea0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
18eb0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
18ec0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18ed0 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
18ee0 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 9 /* Ta
18ef0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
18f00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
18f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18f20 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 DROP_INDEX
18f30 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 10 /* Ind
18f40 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
18f50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
18f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
18f70 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 ROP_TABLE
18f80 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 11 /* Tabl
18f90 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
18fa0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
18fb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
18fc0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 OP_TEMP_INDEX
18fd0 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 12 /* Index
18fe0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
18ff0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
19000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
19010 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 P_TEMP_TABLE
19020 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 13 /* Table
19030 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
19040 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
19050 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
19060 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 _TEMP_TRIGGER
19070 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 14 /* Trigger
19080 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
19090 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
190a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
190b0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 TEMP_VIEW
190c0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 15 /* View Nam
190d0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
190e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
190f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
19100 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 RIGGER 1
19110 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 6 /* Trigger N
19120 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
19130 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
19140 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 e SQLITE_DROP_VI
19150 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 EW 17
19160 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
19170 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
19180 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
19190 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 SQLITE_INSERT
191a0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 18
191b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
191c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
191d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
191e0 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 SQLITE_PRAGMA
191f0 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 19
19200 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 /* Pragma Name
19210 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 1st arg or N
19220 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ULL */.#define S
19230 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 QLITE_READ
19240 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 20
19250 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
19260 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
19270 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
19280 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 LITE_SELECT
19290 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 21 /
192a0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
192b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
192c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
192d0 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 ITE_TRANSACTION
192e0 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 22 /*
192f0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 Operation
19300 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
19310 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
19320 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 TE_UPDATE
19330 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
19340 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
19350 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
19360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
19370 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 E_ATTACH
19380 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 24 /* F
19390 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e ilename N
193a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
193b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
193c0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 _DETACH
193d0 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 25 /* Da
193e0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 tabase Name NU
193f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
19400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
19410 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 ALTER_TABLE
19420 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 26 /* Dat
19430 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 abase Name Tab
19440 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
19450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
19460 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 EINDEX
19470 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 27 /* Inde
19480 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c x Name NULL
19490 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
194a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e define SQLITE_AN
194b0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 ALYZE
194c0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 28 /* Table
194d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
194e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
194f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
19500 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ATE_VTABLE
19510 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 29 /* Table
19520 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
19530 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
19540 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
19550 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 _VTABLE
19560 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 30 /* Table N
19570 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
19580 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
19590 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 ine SQLITE_FUNCT
195a0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 ION
195b0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 31 /* NULL
195c0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e Function
195d0 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 Name */.#defi
195e0 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f ne SQLITE_SAVEPO
195f0 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 INT 3
19600 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
19610 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 Savepoint
19620 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
19630 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 e SQLITE_COPY
19640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
19650 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 /* No longer
19660 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
19670 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 API3REF: Tracing
19680 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 And Profiling F
19690 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 unctions.**.** T
196a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
196b0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 gister callback
196c0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 functions that c
196d0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a an be used for.*
196e0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 * tracing and pr
196f0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 ofiling the exec
19700 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 ution of SQL sta
19710 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e tements..**.** ^
19720 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
19730 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
19740 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 by sqlite3_trac
19750 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 e() is invoked a
19760 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d t.** various tim
19770 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 es when an SQL s
19780 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e tatement is bein
19790 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 g run by [sqlite
197a0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 3_step()]..** ^T
197b0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 he sqlite3_trace
197c0 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 () callback is i
197d0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 nvoked with a UT
197e0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 F-8 rendering of
197f0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 the.** SQL stat
19800 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 ement text as th
19810 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 e statement firs
19820 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 t begins executi
19830 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f ng..** ^(Additio
19840 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 nal sqlite3_trac
19850 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 e() callbacks mi
19860 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 ght occur.** as
19870 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 each triggered s
19880 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 ubprogram is ent
19890 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 ered. The callb
198a0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 acks for trigger
198b0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 s.** contain a U
198c0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 TF-8 SQL comment
198d0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 that identifies
198e0 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a the trigger.)^.
198f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 **.** ^The callb
19900 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
19910 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 istered by sqlit
19920 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 e3_profile() is
19930 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 invoked.** as ea
19940 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ch SQL statement
19950 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 finishes. ^The
19960 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 profile callbac
19970 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 k contains.** th
19980 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 e original state
19990 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e ment text and an
199a0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c estimate of wal
199b0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 l-clock time.**
199c0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 of how long that
199d0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 statement took
199e0 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 to run..*/.void
199f0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 *sqlite3_trace(s
19a00 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 qlite3*, void(*x
19a10 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e Trace)(void*,con
19a20 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a st char*), void*
19a30 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 );.SQLITE_EXPERI
19a40 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c MENTAL void *sql
19a50 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c ite3_profile(sql
19a60 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a ite3*,. void(*
19a70 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c xProfile)(void*,
19a80 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 const char*,sqli
19a90 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 te3_uint64), voi
19aa0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
19ab0 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 3REF: Query Prog
19ac0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a ress Callbacks.*
19ad0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
19ae0 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 ne configures a
19af0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
19b00 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 n - the.** progr
19b10 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 ess callback - t
19b20 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 hat is invoked p
19b30 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 eriodically duri
19b40 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 ng long.** runni
19b50 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c ng calls to [sql
19b60 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 ite3_exec()], [s
19b70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 qlite3_step()] a
19b80 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 nd.** [sqlite3_g
19b90 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e et_table()]. An
19ba0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 example use for
19bb0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 this.** interfa
19bc0 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 ce is to keep a
19bd0 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 GUI updated duri
19be0 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 ng a large query
19bf0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
19c00 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 progress callbac
19c10 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 k returns non-ze
19c20 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f ro, the operatio
19c30 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 n is.** interrup
19c40 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 ted. This featu
19c50 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 re can be used t
19c60 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a o implement a.**
19c70 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e "Cancel" button
19c80 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 on a GUI progre
19c90 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a ss dialog box..*
19ca0 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 *.** The progres
19cb0 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e s handler must n
19cc0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
19cd0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
19ce0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
19cf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
19d00 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 invoked the prog
19d10 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a ress handler..**
19d20 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
19d30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
19d40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
19d50 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
19d60 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
19d70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
19d80 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
19d90 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
19da0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
19db0 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 **.*/.void sqlit
19dc0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 e3_progress_hand
19dd0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e ler(sqlite3*, in
19de0 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 t, int(*)(void*)
19df0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
19e00 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 CAPI3REF: Openi
19e10 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 ng A New Databas
19e20 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a e Connection.**.
19e30 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
19e40 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 es open an SQLit
19e50 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
19e60 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 whose name is gi
19e70 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 ven by the.** fi
19e80 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e lename argument.
19e90 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 ^The filename a
19ea0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 rgument is inter
19eb0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 preted as UTF-8
19ec0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
19ed0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
19ee0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 3_open_v2() and
19ef0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 as UTF-16 in the
19f00 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 native byte.**
19f10 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 order for sqlite
19f20 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 3_open16(). ^(A
19f30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
19f40 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 tion] handle is
19f50 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 usually.** retur
19f60 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 ned in *ppDb, ev
19f70 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f en if an error o
19f80 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 ccurs. The only
19f90 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 exception is th
19fa0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 at.** if SQLite
19fb0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
19fc0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 ocate memory to
19fd0 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 hold the [sqlite
19fe0 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 3] object,.** a
19ff0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 NULL will be wri
1a000 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 tten into *ppDb
1a010 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 instead of a poi
1a020 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c nter to the [sql
1a030 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e ite3].** object.
1a040 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 )^ ^(If the data
1a050 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 base is opened (
1a060 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 and/or created)
1a070 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 successfully, th
1a080 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b en.** [SQLITE_OK
1a090 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 ] is returned.
1a0a0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 Otherwise an [er
1a0b0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
1a0c0 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a urned.)^ ^The.**
1a0d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1a0e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1a0f0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 errmsg16()] rout
1a100 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 ines can be used
1a110 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e to obtain.** an
1a120 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 English languag
1a130 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 e description of
1a140 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f the error follo
1a150 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f wing a failure o
1a160 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 f any.** of the
1a170 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 sqlite3_open() r
1a180 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e outines..**.** ^
1a190 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f The default enco
1a1a0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 ding for the dat
1a1b0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 abase will be UT
1a1c0 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 F-8 if.** sqlite
1a1d0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
1a1e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
1a1f0 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 called and.** U
1a200 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
1a210 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 ive byte order i
1a220 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 f sqlite3_open16
1a230 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a () is used..**.*
1a240 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * Whether or not
1a250 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
1a260 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e when it is open
1a270 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a ed, resources.**
1a280 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
1a290 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
1a2a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
1a2b0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 e should be rele
1a2c0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 ased by.** passi
1a2d0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
1a2e0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 3_close()] when
1a2f0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 it is no longer
1a300 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
1a310 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e The sqlite3_open
1a320 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
1a330 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
1a340 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 e3_open().** exc
1a350 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 ept that it acce
1a360 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e pts two addition
1a370 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f al parameters fo
1a380 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e r additional con
1a390 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 trol.** over the
1a3a0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
1a3b0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 nnection. ^(The
1a3c0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
1a3d0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f to.** sqlite3_o
1a3e0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b pen_v2() can tak
1a3f0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 e one of.** the
1a400 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 following three
1a410 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c values, optional
1a420 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 ly combined with
1a430 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 the .** [SQLITE
1a440 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 _OPEN_NOMUTEX],
1a450 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
1a460 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 LMUTEX], [SQLITE
1a470 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
1a480 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 E],.** and/or [S
1a490 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
1a4a0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 TECACHE] flags:)
1a4b0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ^.**.** <dl>.**
1a4c0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 ^(<dt>[SQLITE_OP
1a4d0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 EN_READONLY]</dt
1a4e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
1a4f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
1a500 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 in read-only mod
1a510 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 e. If the datab
1a520 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 ase does not.**
1a530 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 already exist, a
1a540 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 n error is retur
1a550 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ned.</dd>)^.**.*
1a560 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f * ^(<dt>[SQLITE_
1a570 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c OPEN_READWRITE]<
1a580 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1a590 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
1a5a0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 ed for reading a
1a5b0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f nd writing if po
1a5c0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 ssible, or readi
1a5d0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 ng.** only if th
1a5e0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 e file is write
1a5f0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 protected by the
1a600 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
1a610 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a m. In either.**
1a620 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 case the databa
1a630 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 se must already
1a640 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 exist, otherwise
1a650 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
1a660 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a urned.</dd>)^.**
1a670 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
1a680 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
1a690 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ] | [SQLITE_OPEN
1a6a0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a _CREATE]</dt>.**
1a6b0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
1a6c0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
1a6d0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 reading and writ
1a6e0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 ing, and is crea
1a6f0 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 tes it if.** it
1a700 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 does not already
1a710 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 exist. This is
1a720 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 the behavior tha
1a730 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 t is always used
1a740 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
1a750 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
1a760 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 e3_open16().</dd
1a770 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a >)^.** </dl>.**.
1a780 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
1a790 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
1a7a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
1a7b0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a not one of the.*
1a7c0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 * combinations s
1a7d0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e hown above or on
1a7e0 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 e of the combina
1a7f0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 tions shown abov
1a800 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 e combined.** wi
1a810 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
1a820 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 PEN_NOMUTEX], [S
1a830 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
1a840 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 UTEX],.** [SQLIT
1a850 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
1a860 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 HE] and/or [SQLI
1a870 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
1a880 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 CHE] flags,.** t
1a890 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
1a8a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
1a8b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 *.** ^If the [SQ
1a8c0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
1a8d0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 X] flag is set,
1a8e0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
1a8f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
1a900 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c opens in the mul
1a910 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
1a920 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f ding mode] as lo
1a930 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 ng as the single
1a940 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 -thread.** mode
1a950 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 has not been set
1a960 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
1a970 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 or start-time.
1a980 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
1a990 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
1a9a0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 EX] flag is set
1a9b0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
1a9c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 e connection ope
1a9d0 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 ns.** in the ser
1a9e0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
1a9f0 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 ng mode] unless
1aa00 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 single-thread wa
1aa10 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 s.** previously
1aa20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 selected at comp
1aa30 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 ile-time or star
1aa40 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 t-time..** ^The
1aa50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
1aa60 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 REDCACHE] flag c
1aa70 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
1aa80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
1aa90 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 be.** eligible
1aaa0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 to use [shared c
1aab0 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 ache mode], rega
1aac0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
1aad0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a r or not shared.
1aae0 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 ** cache is enab
1aaf0 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 led using [sqlit
1ab00 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
1ab10 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 _cache()]. ^The
1ab20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
1ab30 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 _PRIVATECACHE] f
1ab40 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 lag causes the d
1ab50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1ab60 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 on to not.** par
1ab70 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 ticipate in [sha
1ab80 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 red cache mode]
1ab90 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e even if it is en
1aba0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 abled..**.** ^If
1abb0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
1abc0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 ":memory:", the
1abd0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d n a private, tem
1abe0 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 porary in-memory
1abf0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 database.** is
1ac00 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 created for the
1ac10 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 connection. ^Th
1ac20 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 is in-memory dat
1ac30 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 abase will vanis
1ac40 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 h when.** the da
1ac50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1ac60 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 n is closed. Fu
1ac70 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
1ac80 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a SQLite might.**
1ac90 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 make use of add
1aca0 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 itional special
1acb0 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 filenames that b
1acc0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a egin with the ":
1acd0 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 " character..**
1ace0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 It is recommende
1acf0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 d that when a da
1ad00 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
1ad10 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 actually does be
1ad20 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a gin with.** a ":
1ad30 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 " character you
1ad40 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 should prefix th
1ad50 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 e filename with
1ad60 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 a pathname such
1ad70 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 as.** "./" to av
1ad80 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a oid ambiguity..*
1ad90 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c *.** ^If the fil
1ada0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 ename is an empt
1adb0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 y string, then a
1adc0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 private, tempor
1add0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 ary.** on-disk d
1ade0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 atabase will be
1adf0 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 created. ^This
1ae00 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 private database
1ae10 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f will be.** auto
1ae20 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 matically delete
1ae30 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 d as soon as the
1ae40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1ae50 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a tion is closed..
1ae60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 **.** ^The fourt
1ae70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
1ae80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1ae90 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
1aea0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1aeb0 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 vfs] object that
1aec0 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 defines the ope
1aed0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e rating system in
1aee0 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 terface that.**
1aef0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 the new database
1af00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 connection shou
1af10 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 ld use. ^If the
1af20 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
1af30 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 r is.** a NULL p
1af40 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 ointer then the
1af50 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
1af60 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 _vfs] object is
1af70 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e used..**.** <b>N
1af80 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 ote to Windows u
1af90 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 sers:</b> The e
1afa0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 ncoding used for
1afb0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 the filename ar
1afc0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c gument.** of sql
1afd0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
1afe0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1aff0 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c ) must be UTF-8,
1b000 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a not whatever.**
1b010 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 codepage is cur
1b020 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 rently defined.
1b030 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 Filenames conta
1b040 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f ining internatio
1b050 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 nal.** character
1b060 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 s must be conver
1b070 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 ted to UTF-8 pri
1b080 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 or to passing th
1b090 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 em into.** sqlit
1b0a0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
1b0b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
1b0c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f */.int sqlite3_o
1b0d0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 pen(. const cha
1b0e0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
1b0f0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
1b100 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
1b110 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
1b120 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
1b130 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
1b140 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 e */.);.int sqli
1b150 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f te3_open16(. co
1b160 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 nst void *filena
1b170 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
1b180 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
1b190 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 16) */. sqlite3
1b1a0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
1b1b0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
1b1c0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
1b1d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
1b1e0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 _v2(. const cha
1b1f0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
1b200 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
1b210 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
1b220 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c sqlite3 **ppDb,
1b230 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
1b240 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
1b250 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 e */. int flags
1b260 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
1b270 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e * Flags */. con
1b280 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 st char *zVfs
1b290 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
1b2a0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 VFS module to us
1b2b0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.);../*.** C
1b2c0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 API3REF: Error C
1b2d0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 odes And Message
1b2e0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
1b2f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 ite3_errcode() i
1b300 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
1b310 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 the numeric [re
1b320 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a sult code] or.**
1b330 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
1b340 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 t code] for the
1b350 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c most recent fail
1b360 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 ed sqlite3_* API
1b370 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 call.** associa
1b380 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 ted with a [data
1b390 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1b3a0 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 . If a prior API
1b3b0 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 call failed.**
1b3c0 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 but the most rec
1b3d0 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 ent API call suc
1b3e0 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 ceeded, the retu
1b3f0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a rn value from.**
1b400 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
1b410 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e () is undefined.
1b420 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ^The sqlite3_e
1b430 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
1b440 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 ).** interface i
1b450 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 s the same excep
1b460 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 t that it always
1b470 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a returns the .**
1b480 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
1b490 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 t code] even whe
1b4a0 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c n extended resul
1b4b0 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 t codes are.** d
1b4c0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e isabled..**.** ^
1b4d0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d The sqlite3_errm
1b4e0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 sg() and sqlite3
1b4f0 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 _errmsg16() retu
1b500 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 rn English-langu
1b510 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 age.** text that
1b520 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 describes the e
1b530 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 rror, as either
1b540 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 UTF-8 or UTF-16
1b550 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
1b560 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c ^(Memory to hol
1b570 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 d the error mess
1b580 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 age string is ma
1b590 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 naged internally
1b5a0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
1b5b0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 tion does not ne
1b5c0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 ed to worry abou
1b5d0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 t freeing the re
1b5e0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 sult..** However
1b5f0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 , the error stri
1b600 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 ng might be over
1b610 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c written or deall
1b620 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 ocated by.** sub
1b630 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
1b640 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
1b650 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e terface function
1b660 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 s.)^.**.** When
1b670 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
1b680 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
1b690 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 is in use, it mi
1b6a0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 ght be the.** ca
1b6b0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 se that a second
1b6c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e error occurs on
1b6d0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
1b6e0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ad in between.**
1b6f0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 the time of the
1b700 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 first error and
1b710 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 the call to the
1b720 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a se interfaces..*
1b730 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 * When that happ
1b740 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 ens, the second
1b750 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
1b760 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 ported since the
1b770 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 se.** interfaces
1b780 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 always report t
1b790 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 he most recent r
1b7a0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 esult. To avoid
1b7b0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 .** this, each t
1b7c0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e hread can obtain
1b7d0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f exclusive use o
1b7e0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
1b7f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
1b800 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 by invoking [sq
1b810 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
1b820 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d r]([sqlite3_db_m
1b830 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 utex](D)) before
1b840 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f beginning.** to
1b850 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b use D and invok
1b860 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
1b870 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 ex_leave]([sqlit
1b880 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
1b890 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 after.** all ca
1b8a0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 lls to the inter
1b8b0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 faces listed her
1b8c0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e e are completed.
1b8d0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 .**.** If an int
1b8e0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 erface fails wit
1b8f0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c h SQLITE_MISUSE,
1b900 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
1b910 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 interface.** was
1b920 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 invoked incorre
1b930 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c ctly by the appl
1b940 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 ication. In tha
1b950 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 t case, the.** e
1b960 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
1b970 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 ssage may or may
1b980 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a not be set..*/.
1b990 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 int sqlite3_errc
1b9a0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
1b9b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 ;.int sqlite3_ex
1b9c0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 tended_errcode(s
1b9d0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e qlite3 *db);.con
1b9e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
1b9f0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a _errmsg(sqlite3*
1ba00 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
1ba10 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
1ba20 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
1ba30 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
1ba40 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
1ba50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
1ba60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1ba70 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 t} {prepared sta
1ba80 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 tements}.**.** A
1ba90 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
1baa0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 is object repres
1bab0 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 ents a single SQ
1bac0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 L statement..**
1bad0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 This object is v
1bae0 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 ariously known a
1baf0 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 s a "prepared st
1bb00 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a atement" or a.**
1bb10 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 "compiled SQL s
1bb20 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d tatement" or sim
1bb30 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d ply as a "statem
1bb40 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ent"..**.** The
1bb50 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d life of a statem
1bb60 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 ent object goes
1bb70 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 something like t
1bb80 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a his:.**.** <ol>.
1bb90 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 ** <li> Create t
1bba0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 he object using
1bbb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1bbc0 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 _v2()] or a rela
1bbd0 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 ted.** func
1bbe0 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 tion..** <li> Bi
1bbf0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f nd values to [ho
1bc00 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 st parameters] u
1bc10 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
1bc20 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 _bind_*().**
1bc30 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a interfaces..**
1bc40 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 <li> Run the SQ
1bc50 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 L by calling [sq
1bc60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e lite3_step()] on
1bc70 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e e or more times.
1bc80 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 .** <li> Reset t
1bc90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 he statement usi
1bca0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
1bcb0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 t()] then go bac
1bcc0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 k.** to ste
1bcd0 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 p 2. Do this ze
1bce0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ro or more times
1bcf0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f ..** <li> Destro
1bd00 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 y the object usi
1bd10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
1bd20 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c lize()]..** </ol
1bd30 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f >.**.** Refer to
1bd40 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f documentation o
1bd50 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 n individual met
1bd60 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 hods above for a
1bd70 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
1bd80 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 ormation..*/.typ
1bd90 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
1bda0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 te3_stmt sqlite3
1bdb0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 _stmt;../*.** CA
1bdc0 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 PI3REF: Run-time
1bdd0 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 Limits.**.** ^(
1bde0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 This interface a
1bdf0 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f llows the size o
1be00 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 f various constr
1be10 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 ucts to be limit
1be20 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 ed.** on a conne
1be30 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 ction by connect
1be40 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 ion basis. The
1be50 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
1be60 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 is the.** [datab
1be70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1be80 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 whose limit is t
1be90 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 o be set or quer
1bea0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 ied. The.** sec
1beb0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
1bec0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d one of the [lim
1bed0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 it categories] t
1bee0 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 hat define a.**
1bef0 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 class of constru
1bf00 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c cts to be size l
1bf10 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 imited. The thi
1bf20 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
1bf30 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 the.** new limit
1bf40 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 for that constr
1bf50 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 uct. The functi
1bf60 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f on returns the o
1bf70 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a ld limit.)^.**.*
1bf80 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 * ^If the new li
1bf90 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
1bfa0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
1bfb0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
1bfc0 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65 20 6c ..** ^(For the l
1bfd0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 imit category of
1bfe0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 SQLITE_LIMIT_XY
1bff0 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a Z there is a .**
1c000 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 [limits | hard
1c010 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 upper bound].**
1c020 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 set by a compile
1c030 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 -time C preproce
1c040 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 ssor macro named
1c050 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 .** [limits | S
1c060 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a QLITE_MAX_XYZ]..
1c070 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f ** (The "_LIMIT_
1c080 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 " in the name is
1c090 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 changed to "_MA
1c0a0 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 X_".))^.** ^Atte
1c0b0 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 mpts to increase
1c0c0 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 a limit above i
1c0d0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f ts hard upper bo
1c0e0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e und are.** silen
1c0f0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f tly truncated to
1c100 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 the hard upper
1c110 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e bound..**.** Run
1c120 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 -time limits are
1c130 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
1c140 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e e in application
1c150 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a s that manage.**
1c160 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 both their own
1c170 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
1c180 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 e and also datab
1c190 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f ases that are co
1c1a0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 ntrolled.** by u
1c1b0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 ntrusted externa
1c1c0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 l sources. An e
1c1d0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 xample applicati
1c1e0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a on might be a.**
1c1f0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 web browser tha
1c200 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 t has its own da
1c210 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 tabases for stor
1c220 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a ing history and.
1c230 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 ** separate data
1c240 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 bases controlled
1c250 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 by JavaScript a
1c260 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e pplications down
1c270 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 loaded.** off th
1c280 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 e Internet. The
1c290 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
1c2a0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e ses can be given
1c2b0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 the.** large, d
1c2c0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 efault limits.
1c2d0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 Databases manage
1c2e0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f d by external so
1c2f0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 urces can.** be
1c300 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c given much small
1c310 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e er limits design
1c320 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 ed to prevent a
1c330 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 denial of servic
1c340 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 e.** attack. De
1c350 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 velopers might a
1c360 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 lso want to use
1c370 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 the [sqlite3_set
1c380 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a _authorizer()].*
1c390 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 * interface to f
1c3a0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 urther control u
1c3b0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 ntrusted SQL. T
1c3c0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 he size of the d
1c3d0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 atabase.** creat
1c3e0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 ed by an untrust
1c3f0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 ed script can be
1c400 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 contained using
1c410 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 the.** [max_pag
1c420 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 e_count] [PRAGMA
1c430 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e ]..**.** New run
1c440 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 -time limit cate
1c450 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 gories may be ad
1c460 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
1c470 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 leases..*/.int s
1c480 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c qlite3_limit(sql
1c490 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 ite3*, int id, i
1c4a0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a nt newVal);../*.
1c4b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
1c4c0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 -Time Limit Cate
1c4d0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 gories.** KEYWOR
1c4e0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 DS: {limit categ
1c4f0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 ory} {*limit cat
1c500 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 egories}.**.** T
1c510 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 hese constants d
1c520 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 efine various pe
1c530 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 rformance limits
1c540 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
1c550 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 lowered at run-t
1c560 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ime using [sqlit
1c570 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 e3_limit()]..**
1c580 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 The synopsis of
1c590 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 the meanings of
1c5a0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 the various limi
1c5b0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f ts is shown belo
1c5c0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c w..** Additional
1c5d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
1c5e0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 available at [li
1c5f0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e mits | Limits in
1c600 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 SQLite]..**.**
1c610 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 <dl>.** ^(<dt>SQ
1c620 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
1c630 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
1c640 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f e maximum size o
1c650 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 f any string or
1c660 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f BLOB or table ro
1c670 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e w.<dd>)^.**.** ^
1c680 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
1c690 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 T_SQL_LENGTH</dt
1c6a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
1c6b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 imum length of a
1c6c0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c n SQL statement,
1c6d0 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 in bytes.</dd>)
1c6e0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ^.**.** ^(<dt>SQ
1c6f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
1c700 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 N</dt>.** <dd>Th
1c710 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
1c720 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
1c730 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f table definitio
1c740 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 n or in the.** r
1c750 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
1c760 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d SELECT] or the m
1c770 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
1c780 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 columns in an i
1c790 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e ndex.** or in an
1c7a0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f ORDER BY or GRO
1c7b0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 UP BY clause.</d
1c7c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 d>)^.**.** ^(<dt
1c7d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 >SQLITE_LIMIT_EX
1c7e0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a PR_DEPTH</dt>.**
1c7f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1c800 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 depth of the pa
1c810 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 rse tree on any
1c820 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e expression.</dd>
1c830 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 )^.**.** ^(<dt>S
1c840 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
1c850 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e OUND_SELECT</dt>
1c860 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1c870 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 mum number of te
1c880 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e rms in a compoun
1c890 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 d SELECT stateme
1c8a0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a nt.</dd>)^.**.**
1c8b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
1c8c0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e MIT_VDBE_OP</dt>
1c8d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1c8e0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e mum number of in
1c8f0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 structions in a
1c900 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
1c910 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 program.** used
1c920 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 to implement an
1c930 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f SQL statement.</
1c940 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
1c950 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 t>SQLITE_LIMIT_F
1c960 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e UNCTION_ARG</dt>
1c970 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1c980 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 mum number of ar
1c990 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e guments on a fun
1c9a0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ction.</dd>)^.**
1c9b0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
1c9c0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c _LIMIT_ATTACHED<
1c9d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1c9e0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
1c9f0 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 f [ATTACH | atta
1ca00 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e ched databases].
1ca10 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 )^</dd>.**.** ^(
1ca20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
1ca30 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
1ca40 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
1ca50 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
1ca60 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 gth of the patte
1ca70 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 rn argument to t
1ca80 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 he [LIKE] or.**
1ca90 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 [GLOB] operators
1caa0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
1cab0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
1cac0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
1cad0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 R</dt>.** <dd>Th
1cae0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
1caf0 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e of variables in
1cb00 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
1cb10 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 t that can.** be
1cb20 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29 5e 0a 2a bound.</dd>)^.*
1cb30 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 *.** ^(<dt>SQLIT
1cb40 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
1cb50 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
1cb60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
1cb70 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e pth of recursion
1cb80 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f for triggers.</
1cb90 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a dd>)^.** </dl>.*
1cba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1cbb0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 _LIMIT_LENGTH
1cbc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1cbd0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
1cbe0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
1cbf0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
1cc00 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
1cc10 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 TE_LIMIT_COLUMN
1cc20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1cc30 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
1cc40 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
1cc50 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
1cc60 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
1cc70 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
1cc80 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 UND_SELECT
1cc90 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
1cca0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
1ccb0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 _OP
1ccc0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 5.#define
1ccd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
1cce0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 CTION_ARG
1ccf0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
1cd00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 SQLITE_LIMIT_AT
1cd10 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 TACHED
1cd20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
1cd30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
1cd40 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
1cd50 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 TH 8.#defi
1cd60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
1cd70 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 VARIABLE_NUMBER
1cd80 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 9.#def
1cd90 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
1cda0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 _TRIGGER_DEPTH
1cdb0 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 10../*
1cdc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
1cdd0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 mpiling An SQL S
1cde0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 tatement.** KEYW
1cdf0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 ORDS: {SQL state
1ce00 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a ment compiler}.*
1ce10 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 *.** To execute
1ce20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 an SQL query, it
1ce30 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 must first be c
1ce40 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 ompiled into a b
1ce50 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 yte-code.** prog
1ce60 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 ram using one of
1ce70 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
1ce80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
1ce90 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c argument, "db",
1cea0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 is a [database
1ceb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 connection] obta
1cec0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 ined from a.** p
1ced0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 rior successful
1cee0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
1cef0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1cf00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 e3_open_v2()] or
1cf10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
1cf20 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 n16()]. The dat
1cf30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1cf40 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 must not have b
1cf50 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a een closed..**.*
1cf60 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
1cf70 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 ument, "zSql", i
1cf80 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 s the statement
1cf90 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 to be compiled,
1cfa0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 encoded.** as ei
1cfb0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
1cfc0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 F-16. The sqlit
1cfd0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 e3_prepare() and
1cfe0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1cff0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 _v2().** interfa
1d000 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 ces use UTF-8, a
1d010 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
1d020 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 re16() and sqlit
1d030 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1d040 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e ).** use UTF-16.
1d050 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e .**.** ^If the n
1d060 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 Byte argument is
1d070 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c less than zero,
1d080 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 then zSql is re
1d090 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 ad up to the.**
1d0a0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
1d0b0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 nator. ^If nByte
1d0c0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
1d0d0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 , then it is the
1d0e0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 maximum.** numb
1d0f0 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 er of bytes rea
1d100 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 d from zSql. ^W
1d110 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e hen nByte is non
1d120 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a -negative, the.*
1d130 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e * zSql string en
1d140 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 ds at either the
1d150 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 first '\000' or
1d160 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 '\u0000' charac
1d170 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 ter or.** the nB
1d180 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 yte-th byte, whi
1d190 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 chever comes fir
1d1a0 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 st. If the calle
1d1b0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 r knows.** that
1d1c0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 the supplied str
1d1d0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 ing is nul-termi
1d1e0 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 nated, then ther
1d1f0 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 e is a small.**
1d200 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 performance adva
1d210 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e ntage to be gain
1d220 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e ed by passing an
1d230 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 nByte parameter
1d240 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 that.** is equa
1d250 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 l to the number
1d260 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
1d270 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e input string <i>
1d280 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a including</i>.**
1d290 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 the nul-termina
1d2a0 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a tor bytes..**.**
1d2b0 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e ^If pzTail is n
1d2c0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a ot NULL then *pz
1d2d0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 Tail is made to
1d2e0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 point to the fir
1d2f0 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 st byte.** past
1d300 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
1d310 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 irst SQL stateme
1d320 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 nt in zSql. The
1d330 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 se routines only
1d340 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 .** compile the
1d350 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 first statement
1d360 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 in zSql, so *pzT
1d370 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e ail is left poin
1d380 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 ting to.** what
1d390 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c remains uncompil
1d3a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 ed..**.** ^*ppSt
1d3b0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 mt is left point
1d3c0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 ing to a compile
1d3d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
1d3e0 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 ement] that can
1d3f0 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 be.** executed u
1d400 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 sing [sqlite3_st
1d410 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 ep()]. ^If ther
1d420 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a e is an error, *
1d430 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a ppStmt is set.**
1d440 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 to NULL. ^If t
1d450 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f he input text co
1d460 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 ntains no SQL (i
1d470 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 f the input is a
1d480 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e n empty.** strin
1d490 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 g or a comment)
1d4a0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 then *ppStmt is
1d4b0 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 set to NULL..**
1d4c0 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 The calling proc
1d4d0 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 edure is respons
1d4e0 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e ible for deletin
1d4f0 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a g the compiled.*
1d500 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 * SQL statement
1d510 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
1d520 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 inalize()] after
1d530 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 it has finished
1d540 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 with it..** ppS
1d550 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e tmt may not be N
1d560 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 ULL..**.** ^On s
1d570 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 uccess, the sqli
1d580 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 te3_prepare() fa
1d590 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 mily of routines
1d5a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1d5b0 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 OK];.** otherwis
1d5c0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
1d5d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
1d5e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1d5f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e _prepare_v2() an
1d600 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
1d610 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 e16_v2() interfa
1d620 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d ces are.** recom
1d630 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e mended for all n
1d640 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 ew programs. The
1d650 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 two older inter
1d660 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e faces are retain
1d670 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 ed.** for backwa
1d680 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
1d690 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 y, but their use
1d6a0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e is discouraged.
1d6b0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 .** ^In the "v2"
1d6c0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
1d6d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
1d6e0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 ent.** that is r
1d6f0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 eturned (the [sq
1d700 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
1d710 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 ct) contains a c
1d720 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 opy of the.** or
1d730 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e iginal SQL text.
1d740 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 This causes the
1d750 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1d760 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a ] interface to.*
1d770 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 * behave differe
1d780 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 ntly in three wa
1d790 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a ys:.**.** <ol>.*
1d7a0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 * <li>.** ^If th
1d7b0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
1d7c0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 a changes, inste
1d7d0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 ad of returning
1d7e0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 [SQLITE_SCHEMA]
1d7f0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 as it.** always
1d800 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c used to do, [sql
1d810 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
1d820 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 l automatically
1d830 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 recompile the SQ
1d840 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 L.** statement a
1d850 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 nd try to run it
1d860 20 61 67 61 69 6e 2e 20 20 5e 49 66 20 74 68 65 again. ^If the
1d870 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e schema has chan
1d880 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 ged in.** a way
1d890 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 that makes the s
1d8a0 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 tatement no long
1d8b0 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 er valid, [sqlit
1d8c0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
1d8d0 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 still.** return
1d8e0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e [SQLITE_SCHEMA].
1d8f0 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 But unlike the
1d900 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 legacy behavior
1d910 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 , [SQLITE_SCHEMA
1d920 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 ] is.** now a fa
1d930 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c tal error. Call
1d940 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
1d950 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e pare_v2()] again
1d960 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 will not make t
1d970 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 he.** error go a
1d980 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 way. Note: use
1d990 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
1d9a0 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 )] to find the t
1d9b0 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 ext.** of the pa
1d9c0 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 rsing error that
1d9d0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b results in an [
1d9e0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 SQLITE_SCHEMA] r
1d9f0 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a eturn..** </li>.
1da00 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 **.** <li>.** ^W
1da10 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 hen an error occ
1da20 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 urs, [sqlite3_st
1da30 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ep()] will retur
1da40 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 n one of the det
1da50 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 ailed.** [error
1da60 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e codes] or [exten
1da70 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d ded error codes]
1da80 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 . ^The legacy b
1da90 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 ehavior was that
1daa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
1dab0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 p()] would only
1dac0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 return a generic
1dad0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
1dae0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 result code.** a
1daf0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
1db00 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f on would have to
1db10 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 make a second c
1db20 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
1db30 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f reset()].** in o
1db40 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 rder to find the
1db50 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 underlying caus
1db60 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d e of the problem
1db70 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 . With the "v2"
1db80 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 prepare.** inter
1db90 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 faces, the under
1dba0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 lying reason for
1dbb0 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 the error is re
1dbc0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
1dbd0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a ly..** </li>.**.
1dbe0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
1dbf0 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 5b 70 he value of a [p
1dc00 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 arameter | host
1dc10 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 parameter] in th
1dc20 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d e WHERE clause m
1dc30 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74 ight.** change t
1dc40 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f he query plan fo
1dc50 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 r a statement, t
1dc60 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
1dc70 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61 75 74 6f t may be.** auto
1dc80 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 matically recomp
1dc90 69 6c 65 64 20 28 61 73 20 69 66 20 74 68 65 72 iled (as if ther
1dca0 65 20 68 61 64 20 62 65 65 6e 20 61 20 73 63 68 e had been a sch
1dcb0 65 6d 61 20 63 68 61 6e 67 65 29 20 6f 6e 20 74 ema change) on t
1dcc0 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 5b 73 71 he first .** [sq
1dcd0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 lite3_step()] ca
1dce0 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 ll following any
1dcf0 20 63 68 61 6e 67 65 20 74 6f 20 74 68 65 20 0a change to the .
1dd00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
1dd10 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 _text | bindings
1dd20 5d 20 6f 66 20 74 68 65 20 5b 70 61 72 61 6d 65 ] of the [parame
1dd30 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a ter]. .** </li>.
1dd40 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 ** </ol>.*/.int
1dd50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
1dd60 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
1dd70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
1dd80 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
1dd90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
1dda0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
1ddb0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
1ddc0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 -8 encoded */.
1ddd0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
1dde0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
1ddf0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
1de00 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
1de10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
1de20 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
1de30 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
1de40 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
1de50 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f r **pzTail /
1de60 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
1de70 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
1de80 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 of zSql */.);.i
1de90 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
1dea0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 re_v2(. sqlite3
1deb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
1dec0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
1ded0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
1dee0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 har *zSql,
1def0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
1df00 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 t, UTF-8 encoded
1df10 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
1df20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
1df30 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
1df40 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
1df50 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
1df60 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
1df70 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
1df80 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
1df90 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
1dfa0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
1dfb0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
1dfc0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
1dfd0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
1dfe0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 _prepare16(. sq
1dff0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
1e000 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
1e010 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
1e020 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
1e030 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
1e040 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
1e050 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
1e060 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
1e070 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
1e080 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
1e090 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
1e0a0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
1e0b0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
1e0c0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
1e0d0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
1e0e0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
1e0f0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
1e100 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
1e110 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 zSql */.);.int s
1e120 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1e130 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
1e140 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
1e150 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
1e160 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
1e170 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f d *zSql, /
1e180 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
1e190 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
1e1a0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
1e1b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
1e1c0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
1e1d0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
1e1e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
1e1f0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
1e200 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
1e210 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1e220 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 t void **pzTail
1e230 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
1e240 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
1e250 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
1e260 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
1e270 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 REF: Retrieving
1e280 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a Statement SQL.**
1e290 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 .** ^This interf
1e2a0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
1e2b0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 to retrieve a sa
1e2c0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ved copy of the
1e2d0 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 original.** SQL
1e2e0 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 text used to cre
1e2f0 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 ate a [prepared
1e300 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 statement] if th
1e310 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 at statement was
1e320 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 .** compiled usi
1e330 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
1e340 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1e350 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
1e360 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f pare16_v2()]..*/
1e370 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1e380 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 ite3_sql(sqlite3
1e390 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
1e3a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1e3b0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 Dynamically Type
1e3c0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a d Value Object.*
1e3d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f * KEYWORDS: {pro
1e3e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
1e3f0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 alue} {unprotect
1e400 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1e410 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 }.**.** SQLite u
1e420 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f ses the sqlite3_
1e430 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 value object to
1e440 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 represent all va
1e450 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e lues.** that can
1e460 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 be stored in a
1e470 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 database table.
1e480 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
1e490 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f mic typing.** fo
1e4a0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 r the values it
1e4b0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 stores. ^Values
1e4c0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 stored in sqlit
1e4d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1e4e0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 .** can be integ
1e4f0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
1e500 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
1e510 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
1e520 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 ULL..**.** An sq
1e530 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1e540 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 ct may be either
1e550 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 "protected" or
1e560 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a "unprotected"..*
1e570 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 * Some interface
1e580 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 s require a prot
1e590 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
1e5a0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 lue. Other inte
1e5b0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 rfaces.** will a
1e5c0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 ccept either a p
1e5d0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 rotected or an u
1e5e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
1e5f0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 e3_value..** Eve
1e600 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ry interface tha
1e610 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 t accepts sqlite
1e620 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 3_value argument
1e630 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 s specifies.** w
1e640 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 hether or not it
1e650 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 requires a prot
1e660 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
1e670 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 lue..**.** The t
1e680 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 erms "protected"
1e690 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 and "unprotecte
1e6a0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 d" refer to whet
1e6b0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 her or not.** a
1e6c0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 mutex is held.
1e6d0 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 A internal mutex
1e6e0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 is held for a p
1e6f0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
1e700 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1e710 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 but no mutex is
1e720 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 held for an unp
1e730 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
1e740 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1e750 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 . If SQLite is
1e760 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 compiled to be s
1e770 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a ingle-threaded.*
1e780 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f * (with [SQLITE_
1e790 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e THREADSAFE=0] an
1e7a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f d with [sqlite3_
1e7b0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 threadsafe()] re
1e7c0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 turning 0).** or
1e7d0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 if SQLite is ru
1e7e0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 n in one of redu
1e7f0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 ced mutex modes
1e800 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
1e810 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
1e820 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
1e830 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a IG_MULTITHREAD].
1e840 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 ** then there is
1e850 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 no distinction
1e860 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
1e870 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
1e880 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
1e890 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 ue objects and t
1e8a0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 hey can be used
1e8b0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e interchangeably.
1e8c0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f However,.** fo
1e8d0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 r maximum code p
1e8e0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 ortability it is
1e8f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
1e900 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a t applications.*
1e910 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 * still make the
1e920 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
1e930 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f ween between pro
1e940 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f tected and unpro
1e950 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
1e960 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
1e970 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 even when not st
1e980 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e rictly required.
1e990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1e9a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1e9b0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 s that are passe
1e9c0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 d as parameters
1e9d0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c into the.** impl
1e9e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 ementation of [a
1e9f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
1ea00 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
1ea10 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e ] are protected.
1ea20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1ea30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 _value object re
1ea40 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
1ea50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
1ea60 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 ue()] is unprote
1ea70 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 cted..** Unprote
1ea80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
1ea90 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f ue objects may o
1eaa0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 nly be used with
1eab0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
1eac0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 ult_value()] and
1ead0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 [sqlite3_bind_v
1eae0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 alue()]..** The
1eaf0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
1eb00 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 lob | sqlite3_va
1eb10 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 lue_type()] fami
1eb20 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 ly of.** interfa
1eb30 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 ces require prot
1eb40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
1eb50 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a lue objects..*/.
1eb60 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d typedef struct M
1eb70 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 em sqlite3_value
1eb80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1eb90 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 F: SQL Function
1eba0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a Context Object.*
1ebb0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 *.** The context
1ebc0 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c in which an SQL
1ebd0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 function execut
1ebe0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 es is stored in
1ebf0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f an.** sqlite3_co
1ec00 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e ntext object. ^
1ec10 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 A pointer to an
1ec20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
1ec30 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 object.** is alw
1ec40 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 ays first parame
1ec50 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 ter to [applicat
1ec60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
1ec70 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 functions]..** T
1ec80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
1ec90 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
1eca0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
1ecb0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 on will pass thi
1ecc0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 s.** pointer thr
1ecd0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 ough into calls
1ece0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 to [sqlite3_resu
1ecf0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 lt_int | sqlite3
1ed00 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b _result()],.** [
1ed10 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
1ed20 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 e_context()], [s
1ed30 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
1ed40 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
1ed50 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
1ed60 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f le()], [sqlite3_
1ed70 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a get_auxdata()],.
1ed80 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 ** and/or [sqlit
1ed90 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
1eda0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 ]..*/.typedef st
1edb0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e ruct sqlite3_con
1edc0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e text sqlite3_con
1edd0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 text;../*.** CAP
1ede0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 I3REF: Binding V
1edf0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 alues To Prepare
1ee00 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 d Statements.**
1ee10 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 KEYWORDS: {host
1ee20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 parameter} {host
1ee30 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f parameters} {ho
1ee40 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d st parameter nam
1ee50 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 e}.** KEYWORDS:
1ee60 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 {SQL parameter}
1ee70 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d {SQL parameters}
1ee80 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 {parameter bind
1ee90 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 ing}.**.** ^(In
1eea0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1eeb0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 t text input to
1eec0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1eed0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 _v2()] and its v
1eee0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 ariants,.** lite
1eef0 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c rals may be repl
1ef00 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d aced by a [param
1ef10 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 eter] that match
1ef20 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 es one of follow
1ef30 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 ing.** templates
1ef40 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
1ef50 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 <li> ?.** <li>
1ef60 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a ?NNN.** <li> :
1ef70 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 VVV.** <li> @VV
1ef80 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a V.** <li> $VVV.
1ef90 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ul>.**.** I
1efa0 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 n the templates
1efb0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 above, NNN repre
1efc0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 sents an integer
1efd0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 literal,.** and
1efe0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 VVV represents
1eff0 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 an alphanumeric
1f000 69 64 65 6e 74 69 66 65 72 2e 29 5e 20 20 5e 54 identifer.)^ ^T
1f010 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 he values of the
1f020 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 se.** parameters
1f030 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 (also called "h
1f040 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
1f050 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 mes" or "SQL par
1f060 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e ameters").** can
1f070 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 be set using th
1f080 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
1f090 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 () routines defi
1f0a0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 ned here..**.**
1f0b0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
1f0c0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
1f0d0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
1f0e0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a ines is always.*
1f0f0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 * a pointer to t
1f100 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
1f110 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
1f120 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 d from.** [sqlit
1f130 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1f140 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
1f150 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 ..**.** ^The sec
1f160 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
1f170 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
1f180 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 SQL parameter t
1f190 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 o be set..** ^Th
1f1a0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 e leftmost SQL p
1f1b0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 arameter has an
1f1c0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 index of 1. ^Wh
1f1d0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 en the same name
1f1e0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 d.** SQL paramet
1f1f0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 er is used more
1f200 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e than once, secon
1f210 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
1f220 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 .** occurrences
1f230 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e have the same in
1f240 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 dex as the first
1f250 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 occurrence..**
1f260 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e ^The index for n
1f270 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 amed parameters
1f280 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 can be looked up
1f290 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
1f2a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1f2b0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 meter_index()] A
1f2c0 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 PI if desired.
1f2d0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f ^The index.** fo
1f2e0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 r "?NNN" paramet
1f2f0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 ers is the value
1f300 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 of NNN..** ^The
1f310 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 NNN value must
1f320 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 be between 1 and
1f330 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 the [sqlite3_li
1f340 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 mit()].** parame
1f350 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ter [SQLITE_LIMI
1f360 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
1f370 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 R] (default valu
1f380 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e e: 999)..**.** ^
1f390 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
1f3a0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 nt is the value
1f3b0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 to bind to the p
1f3c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
1f3d0 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 ^(In those routi
1f3e0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 nes that have a
1f3f0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
1f400 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 its value is th
1f410 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 e.** number of b
1f420 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 ytes in the para
1f430 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c meter. To be cl
1f440 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 ear: the value i
1f450 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
1f460 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 of <u>bytes</u>
1f470 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f in the value, no
1f480 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
1f490 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a characters.)^.**
1f4a0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 ^If the fourth
1f4b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 parameter is neg
1f4c0 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 ative, the lengt
1f4d0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 h of the string
1f4e0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 is.** the number
1f4f0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 of bytes up to
1f500 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 the first zero t
1f510 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a erminator..**.**
1f520 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 ^The fifth argu
1f530 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
1f540 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c bind_blob(), sql
1f550 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
1f560 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 , and.** sqlite3
1f570 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 _bind_text16() i
1f580 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 s a destructor u
1f590 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f sed to dispose o
1f5a0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a f the BLOB or.**
1f5b0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 string after SQ
1f5c0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 Lite has finishe
1f5d0 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66 20 74 d with it. ^If t
1f5e0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
1f5f0 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 t is.** the spec
1f600 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 ial value [SQLIT
1f610 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 E_STATIC], then
1f620 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 SQLite assumes t
1f630 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 hat the.** infor
1f640 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 mation is in sta
1f650 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 tic, unmanaged s
1f660 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f pace and does no
1f670 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 t need to be fre
1f680 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 ed..** ^If the f
1f690 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 ifth argument ha
1f6a0 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c s the value [SQL
1f6b0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 ITE_TRANSIENT],
1f6c0 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d then.** SQLite m
1f6d0 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 akes its own pri
1f6e0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
1f6f0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c data immediatel
1f700 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 y, before.** the
1f710 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
1f720 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
1f730 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 s..**.** ^The sq
1f740 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
1f750 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 lob() routine bi
1f760 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 nds a BLOB of le
1f770 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 ngth N that.** i
1f780 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 s filled with ze
1f790 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c roes. ^A zerobl
1f7a0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 ob uses a fixed
1f7b0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 amount of memory
1f7c0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 .** (just an int
1f7d0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 eger to hold its
1f7e0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 size) while it
1f7f0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 is being process
1f800 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 ed..** Zeroblobs
1f810 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f are intended to
1f820 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 serve as placeh
1f830 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 olders for BLOBs
1f840 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e whose.** conten
1f850 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 t is later writt
1f860 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c en using.** [sql
1f870 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c ite3_blob_open |
1f880 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f incremental BLO
1f890 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e B I/O] routines.
1f8a0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 .** ^A negative
1f8b0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 value for the ze
1f8c0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 roblob results i
1f8d0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 n a zero-length
1f8e0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 BLOB..**.** ^If
1f8f0 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 any of the sqlit
1f900 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
1f910 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
1f920 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
1f930 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b ter.** for the [
1f940 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1f950 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 nt] or with a pr
1f960 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1f970 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 for which.** [s
1f980 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
1f990 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d as been called m
1f9a0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 ore recently tha
1f9b0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
1f9c0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ()],.** then the
1f9d0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 call will retur
1f9e0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
1f9f0 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 ]. If any sqlit
1fa00 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f e3_bind_().** ro
1fa10 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 utine is passed
1fa20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
1fa30 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 ement] that has
1fa40 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 been finalized,
1fa50 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 the.** result is
1fa60 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
1fa70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e robably harmful.
1fa80 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 .**.** ^Bindings
1fa90 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 are not cleared
1faa0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
1fab0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e _reset()] routin
1fac0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 e..** ^Unbound p
1fad0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e arameters are in
1fae0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c terpreted as NUL
1faf0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 L..**.** ^The sq
1fb00 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 lite3_bind_* rou
1fb10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
1fb20 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
1fb30 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 ess or an.** [er
1fb40 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 ror code] if any
1fb50 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 thing goes wrong
1fb60 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 ..** ^[SQLITE_RA
1fb70 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 NGE] is returned
1fb80 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
1fb90 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 r.** index is ou
1fba0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 t of range. ^[S
1fbb0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 QLITE_NOMEM] is
1fbc0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c returned if mall
1fbd0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a oc() fails..**.*
1fbe0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
1fbf0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1fc00 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a ter_count()],.**
1fc10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1fc20 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
1fc30 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 , and [sqlite3_b
1fc40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
1fc50 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 dex()]..*/.int s
1fc60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1fc70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1fc80 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a int, const void*
1fc90 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 , int n, void(*)
1fca0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 (void*));.int sq
1fcb0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c lite3_bind_doubl
1fcc0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
1fcd0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 int, double);.i
1fce0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1fcf0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
1fd00 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e *, int, int);.in
1fd10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 t sqlite3_bind_i
1fd20 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d nt64(sqlite3_stm
1fd30 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 t*, int, sqlite3
1fd40 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c _int64);.int sql
1fd50 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 ite3_bind_null(s
1fd60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1fd70 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f t);.int sqlite3_
1fd80 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 bind_text(sqlite
1fd90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
1fda0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e nst char*, int n
1fdb0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
1fdc0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
1fdd0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 ind_text16(sqlit
1fde0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
1fdf0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
1fe00 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
1fe10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
1fe20 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 nd_value(sqlite3
1fe30 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
1fe40 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 st sqlite3_value
1fe50 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
1fe60 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 bind_zeroblob(sq
1fe70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1fe80 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a , int n);../*.**
1fe90 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
1fea0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 r Of SQL Paramet
1feb0 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ers.**.** ^This
1fec0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 routine can be u
1fed0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 sed to find the
1fee0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 number of [SQL p
1fef0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e arameters].** in
1ff00 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
1ff10 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 tement]. SQL pa
1ff20 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b rameters are tok
1ff30 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f ens of the.** fo
1ff40 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 rm "?", "?NNN",
1ff50 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 ":AAA", "$AAA",
1ff60 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 or "@AAA" that s
1ff70 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 erve as.** place
1ff80 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 holders for valu
1ff90 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c es that are [sql
1ffa0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
1ffb0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 bound].** to th
1ffc0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 e parameters at
1ffd0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a a later time..**
1ffe0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 .** ^(This routi
1fff0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 ne actually retu
20000 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 rns the index of
20010 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 the largest (ri
20020 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 ghtmost).** para
20030 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 meter. For all f
20040 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e orms except ?NNN
20050 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 , this will corr
20060 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a espond to the.**
20070 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 number of uniqu
20080 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 e parameters. I
20090 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 f parameters of
200a0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 the ?NNN form ar
200b0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 e used,.** there
200c0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 may be gaps in
200d0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a the list.)^.**.*
200e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
200f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
20100 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
20110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
20120 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
20130 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
20140 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
20150 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
20160 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
20170 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
20180 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
20190 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
201a0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 : Name Of A Host
201b0 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a Parameter.**.**
201c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 ^The sqlite3_bi
201d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
201e0 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 e(P,N) interface
201f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 returns.** the
20200 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 name of the N-th
20210 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d [SQL parameter]
20220 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 in the [prepare
20230 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a d statement] P..
20240 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 ** ^(SQL paramet
20250 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 ers of the form
20260 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 "?NNN" or ":AAA"
20270 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 or "@AAA" or "$
20280 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e AAA".** have a n
20290 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 ame which is the
202a0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f string "?NNN" o
202b0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 r ":AAA" or "@AA
202c0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 A" or "$AAA".**
202d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
202e0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
202f0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 the initial ":"
20300 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f or "$" or "@" o
20310 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c r "?".** is incl
20320 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 uded as part of
20330 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e the name.)^.** ^
20340 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 Parameters of th
20350 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f e form "?" witho
20360 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 ut a following i
20370 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e nteger have no n
20380 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 ame.** and are r
20390 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e eferred to as "n
203a0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f ameless" or "ano
203b0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 nymous parameter
203c0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 s"..**.** ^The f
203d0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 irst host parame
203e0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 ter has an index
203f0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a of 1, not 0..**
20400 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 .** ^If the valu
20410 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 e N is out of ra
20420 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d nge or if the N-
20430 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a th parameter is.
20440 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 ** nameless, the
20450 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e n NULL is return
20460 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e ed. ^The return
20470 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 ed string is.**
20480 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 always in UTF-8
20490 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 encoding even if
204a0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d the named param
204b0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 eter was.** orig
204c0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 inally specified
204d0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 as UTF-16 in [s
204e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
204f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
20500 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
20510 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c )]..**.** See al
20520 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
20530 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
20540 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
20550 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
20560 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 er_count()], and
20570 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
20580 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
20590 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 x()]..*/.const c
205a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e har *sqlite3_bin
205b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
205c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
205d0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
205e0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 I3REF: Index Of
205f0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 A Parameter With
20600 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a A Given Name.**
20610 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 .** ^Return the
20620 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 index of an SQL
20630 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 parameter given
20640 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a its name. ^The.
20650 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 ** index value r
20660 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 eturned is suita
20670 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 ble for use as t
20680 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 he second.** par
20690 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
206a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
206b0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e ite3_bind()]. ^
206c0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 A zero.** is ret
206d0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 urned if no matc
206e0 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 hing parameter i
206f0 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 s found. ^The p
20700 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 arameter.** name
20710 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 must be given i
20720 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 n UTF-8 even if
20730 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 the original sta
20740 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 tement.** was pr
20750 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d epared from UTF-
20760 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 16 text using [s
20770 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
20780 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
20790 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
207a0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
207b0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
207c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
207d0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
207e0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
207f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
20800 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 index()]..*/.int
20810 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
20820 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 rameter_index(sq
20830 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e lite3_stmt*, con
20840 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b st char *zName);
20850 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20860 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 : Reset All Bind
20870 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 ings On A Prepar
20880 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a ed Statement.**.
20890 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 ** ^Contrary to
208a0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 the intuition of
208b0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f many, [sqlite3_
208c0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f reset()] does no
208d0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b t reset.** the [
208e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
208f0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e b | bindings] on
20900 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
20910 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 tement]..** ^Use
20920 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f this routine to
20930 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 reset all host
20940 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 parameters to NU
20950 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 LL..*/.int sqlit
20960 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 e3_clear_binding
20970 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 s(sqlite3_stmt*)
20980 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
20990 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c F: Number Of Col
209a0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 umns In A Result
209b0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 Set.**.** ^Retu
209c0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 rn the number of
209d0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
209e0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 result set retur
209f0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 ned by the.** [p
20a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
20a10 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e t]. ^This routin
20a20 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 e returns 0 if p
20a30 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a Stmt is an SQL.*
20a40 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 * statement that
20a50 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e does not return
20a60 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 data (for examp
20a70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e le an [UPDATE]).
20a80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
20a90 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c column_count(sql
20aa0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
20ab0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
20ac0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 EF: Column Names
20ad0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 In A Result Set
20ae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
20af0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
20b00 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 e name assigned
20b10 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 to a particular
20b20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 column.** in the
20b30 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 result set of a
20b40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
20b50 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 ent. ^The sqlit
20b60 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
20b70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 .** interface re
20b80 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
20b90 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
20ba0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
20bb0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 g.** and sqlite3
20bc0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
20bd0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
20be0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 er to a zero-ter
20bf0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
20c00 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 6 string. ^The
20c10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
20c20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 is the [prepared
20c30 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 statement].** t
20c40 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
20c50 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
20c60 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f ement. ^The seco
20c70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
20c80 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 the.** column nu
20c90 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 mber. ^The left
20ca0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e most column is n
20cb0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e umber 0..**.** ^
20cc0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
20cd0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 ing pointer is v
20ce0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 alid until eithe
20cf0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 r the [prepared
20d00 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 statement].** is
20d10 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 destroyed by [s
20d20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
20d30 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 )] or until the
20d40 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 next call to.**
20d50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
20d60 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ame() or sqlite3
20d70 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
20d80 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c on the same col
20d90 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 umn..**.** ^If s
20da0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
20db0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 fails during the
20dc0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 processing of e
20dd0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a ither routine.**
20de0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 (for example du
20df0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f ring a conversio
20e00 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 n from UTF-8 to
20e10 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a UTF-16) then a.*
20e20 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 * NULL pointer i
20e30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
20e40 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 * ^The name of a
20e50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
20e60 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
20e70 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 he "AS" clause f
20e80 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d or.** that colum
20e90 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 n, if there is a
20ea0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 n AS clause. If
20eb0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 there is no AS
20ec0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 clause.** then t
20ed0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 he name of the c
20ee0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 olumn is unspeci
20ef0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 fied and may cha
20f00 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 nge from.** one
20f10 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
20f20 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a e to the next..*
20f30 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
20f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
20f50 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
20f60 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 int N);.const v
20f70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
20f80 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 umn_name16(sqlit
20f90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 e3_stmt*, int N)
20fa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
20fb0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 F: Source Of Dat
20fc0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 a In A Query Res
20fd0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ult.**.** ^These
20fe0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 routines provid
20ff0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 e a means to det
21000 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 ermine the datab
21010 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a ase, table, and.
21020 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 ** table column
21030 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 that is the orig
21040 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c in of a particul
21050 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ar result column
21060 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 in.** [SELECT]
21070 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 statement..** ^T
21080 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
21090 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 atabase or table
210a0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 or column can b
210b0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a e returned as.**
210c0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 either a UTF-8
210d0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 or UTF-16 string
210e0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 . ^The _databas
210f0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
21100 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 rn.** the databa
21110 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 se name, the _ta
21120 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 ble_ routines re
21130 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e turn the table n
21140 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 ame, and.** the
21150 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 origin_ routines
21160 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 return the colu
21170 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 mn name..** ^The
21180 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
21190 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
211a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
211b0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 atement] is dest
211c0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b royed.** using [
211d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
211e0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ()] or until the
211f0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
21200 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
21210 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
21220 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
21230 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 .**.** ^The name
21240 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 s returned are t
21250 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 he original un-a
21260 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 liased names of
21270 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c the.** database,
21280 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 table, and colu
21290 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 mn..**.** ^The f
212a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
212b0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
212c0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 s is a [prepared
212d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
212e0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
212f0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
21300 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
21310 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
21320 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
21330 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
21340 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
21350 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
21360 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c ument..** ^The l
21370 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 eft-most column
21380 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 is column 0 for
21390 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
213a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 **.** ^If the Nt
213b0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
213c0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 d by the stateme
213d0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 nt is an express
213e0 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 ion or.** subque
213f0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 ry and is not a
21400 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 column value, th
21410 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 en all of these
21420 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
21430 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 .** NULL. ^Thes
21440 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 e routine might
21450 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c also return NULL
21460 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
21470 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a ocation error.**
21480 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 occurs. ^Other
21490 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
214a0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
214b0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
214c0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f ase, table,.** o
214d0 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 r column that qu
214e0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
214f0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
21500 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 from..**.** ^As
21510 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
21520 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
21530 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e e whose names en
21540 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 d with "16" retu
21550 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 rn.** UTF-16 enc
21560 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 oded strings and
21570 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 the other funct
21580 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d ions return UTF-
21590 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 8..**.** ^These
215a0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 APIs are only av
215b0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c ailable if the l
215c0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 ibrary was compi
215d0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
215e0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 [SQLITE_ENABLE_C
215f0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 OLUMN_METADATA]
21600 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 C-preprocessor s
21610 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ymbol..**.** If
21620 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
21630 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
21640 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f more of these ro
21650 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 utines against t
21660 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 he same.** prepa
21670 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e red statement an
21680 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 d column at the
21690 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
216a0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a he results are.*
216b0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
216c0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
216d0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
216e0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 ne or more.** [s
216f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
21700 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f tabase_name | co
21710 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e lumn metadata in
21720 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 terfaces].** for
21730 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 the same [prepa
21740 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
21750 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e nd result column
21760 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 .** at the same
21770 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
21780 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
21790 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ned..*/.const ch
217a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
217b0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
217c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
217d0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
217e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
217f0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
21800 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
21810 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
21820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
21830 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 able_name(sqlite
21840 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
21850 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
21860 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
21870 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
21880 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
21890 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
218a0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
218b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
218c0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
218d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
218e0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 origin_name16(sq
218f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
21900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
21910 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 F: Declared Data
21920 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 type Of A Query
21930 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 Result.**.** ^(T
21940 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
21950 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 er is a [prepare
21960 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
21970 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 If this stateme
21980 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d nt is a [SELECT]
21990 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
219a0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
219b0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 the.** returned
219c0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 result set of t
219d0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 hat [SELECT] is
219e0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 a table column (
219f0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 not an.** expres
21a00 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
21a10 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 ) then the decla
21a20 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 red type of the
21a30 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 table.** column
21a40 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 is returned.)^
21a50 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
21a60 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
21a70 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 set is an.** ex
21a80 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
21a90 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c uery, then a NUL
21aa0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
21ab0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 urned..** ^The r
21ac0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
21ad0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 s always UTF-8 e
21ae0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ncoded..**.** ^(
21af0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 For example, giv
21b00 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
21b10 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 schema:.**.** CR
21b20 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 EATE TABLE t1(c1
21b30 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a VARIANT);.**.**
21b40 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 and the followi
21b50 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 ng statement to
21b60 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a be compiled:.**.
21b70 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 ** SELECT c1 + 1
21b80 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a , c1 FROM t1;.**
21b90 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
21ba0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 would return th
21bb0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e e string "VARIAN
21bc0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e T" for the secon
21bd0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 d result.** colu
21be0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 mn (i==1), and a
21bf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
21c00 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 r the first resu
21c10 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 lt column (i==0)
21c20 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 .)^.**.** ^SQLit
21c30 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 e uses dynamic r
21c40 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 un-time typing.
21c50 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 ^So just becaus
21c60 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 e a column.** is
21c70 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e declared to con
21c80 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 tain a particula
21c90 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 r type does not
21ca0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a mean that the.**
21cb0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 data stored in
21cc0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f that column is o
21cd0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 f the declared t
21ce0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a ype. SQLite is.
21cf0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 ** strongly type
21d00 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e d, but the typin
21d10 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 g is dynamic not
21d20 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a static. ^Type.
21d30 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
21d40 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
21d50 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
21d60 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
21d70 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
21d80 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
21d90 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
21da0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
21db0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 ltype(sqlite3_st
21dc0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
21dd0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
21de0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 lumn_decltype16(
21df0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
21e00 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
21e10 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e REF: Evaluate An
21e20 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
21e30 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 *.** After a [pr
21e40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
21e50 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 ] has been prepa
21e60 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 red using either
21e70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
21e80 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
21e90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
21ea0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
21eb0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
21ec0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
21ed0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
21ee0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
21ef0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e e16()], this fun
21f00 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 ction.** must be
21f10 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
21f20 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 ore times to eva
21f30 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d luate the statem
21f40 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ent..**.** The d
21f50 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 etails of the be
21f60 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 havior of the sq
21f70 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 lite3_step() int
21f80 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a erface depend.**
21f90 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 on whether the
21fa0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 statement was pr
21fb0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 epared using the
21fc0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 newer "v2" inte
21fd0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 rface.** [sqlite
21fe0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
21ff0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
22000 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
22010 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 the older legacy
22020 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 .** interface [s
22030 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
22040 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
22050 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 repare16()]. Th
22060 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 e use of the.**
22070 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 new "v2" interfa
22080 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
22090 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 d for new applic
220a0 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c ations but the l
220b0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
220c0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 ce will continue
220d0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
220e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 ..**.** ^In the
220f0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
22100 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
22110 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 ue will be eithe
22120 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c r [SQLITE_BUSY],
22130 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
22140 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ], [SQLITE_ROW],
22150 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
22160 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 or [SQLITE_MISU
22170 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 SE]..** ^With th
22180 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
22190 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 , any of the oth
221a0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 er [result codes
221b0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
221c0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
221d0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 might be returne
221e0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a d as well..**.**
221f0 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 ^[SQLITE_BUSY]
22200 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 means that the d
22210 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 atabase engine w
22220 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 as unable to acq
22230 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 uire the.** data
22240 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 base locks it ne
22250 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f eds to do its jo
22260 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 b. ^If the stat
22270 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d ement is a [COMM
22280 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 IT].** or occurs
22290 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
222a0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
222b0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
222c0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
222d0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
222e0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
222f0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e ot a [COMMIT] an
22300 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 d occurs within
22310 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 a.** explicit tr
22320 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 ansaction then y
22330 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 ou should rollba
22340 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ck the transacti
22350 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e on before.** con
22360 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e tinuing..**.** ^
22370 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 [SQLITE_DONE] me
22380 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 ans that the sta
22390 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 tement has finis
223a0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a hed executing.**
223b0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 successfully.
223c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 sqlite3_step() s
223d0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c hould not be cal
223e0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 led again on thi
223f0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 s virtual.** mac
22400 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 hine without fir
22410 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 st calling [sqli
22420 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 te3_reset()] to
22430 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 reset the virtua
22440 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 l.** machine bac
22450 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c k to its initial
22460 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 state..**.** ^I
22470 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
22480 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 ent being execut
22490 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 ed returns any d
224a0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ata, then [SQLIT
224b0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 E_ROW].** is ret
224c0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 urned each time
224d0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 a new row of dat
224e0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 a is ready for p
224f0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 rocessing by the
22500 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 .** caller. The
22510 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 values may be ac
22520 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 cessed using the
22530 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
22540 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 functions]..** s
22550 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 qlite3_step() is
22560 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f called again to
22570 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 retrieve the ne
22580 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a xt row of data..
22590 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 **.** ^[SQLITE_E
225a0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 RROR] means that
225b0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f a run-time erro
225c0 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e r (such as a con
225d0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 straint.** viola
225e0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 tion) has occurr
225f0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ed. sqlite3_ste
22600 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
22610 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
22620 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 n.** the VM. Mor
22630 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 e information ma
22640 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 y be found by ca
22650 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 lling [sqlite3_e
22660 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 rrmsg()]..** ^Wi
22670 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e th the legacy in
22680 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 terface, a more
22690 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
226a0 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ode (for example
226b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 ,.** [SQLITE_INT
226c0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 ERRUPT], [SQLITE
226d0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 _SCHEMA], [SQLIT
226e0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 E_CORRUPT], and
226f0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e so forth).** can
22700 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 be obtained by
22710 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
22720 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 _reset()] on the
22730 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
22740 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 atement]. ^In t
22750 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
22760 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 e,.** the more s
22770 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
22780 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 de is returned d
22790 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 irectly by sqlit
227a0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a e3_step()..**.**
227b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
227c0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
227d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 this routine was
227e0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 called inapprop
227f0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 riately..** Perh
22800 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 aps it was calle
22810 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 d on a [prepared
22820 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
22830 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 has.** already
22840 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 been [sqlite3_fi
22850 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a nalize | finaliz
22860 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 ed] or on one th
22870 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f at had.** previo
22880 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 usly returned [S
22890 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 QLITE_ERROR] or
228a0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
228b0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 Or it could.** b
228c0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 e the case that
228d0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
228e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
228f0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 being used by tw
22900 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 o or.** more thr
22910 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
22920 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e moment in time.
22930 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 .**.** For all v
22940 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
22950 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c e up to and incl
22960 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 uding 3.6.23.1,
22970 69 74 20 77 61 73 20 72 65 71 75 69 72 65 64 0a it was required.
22980 2a 2a 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ** after sqlite3
22990 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 _step() returned
229a0 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 anything other
229b0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 than [SQLITE_ROW
229c0 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 ] that.** [sqlit
229d0 65 33 5f 72 65 73 65 74 28 29 5d 20 62 65 20 63 e3_reset()] be c
229e0 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 61 6e 79 alled before any
229f0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f subsequent invo
22a00 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c cation of.** sql
22a10 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 ite3_step(). Fa
22a20 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b 65 20 ilure to invoke
22a30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
22a40 5d 20 69 6e 20 74 68 69 73 20 77 61 79 20 77 6f ] in this way wo
22a50 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e uld.** result in
22a60 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 an [SQLITE_MISU
22a70 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 SE] return from
22a80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
22a90 20 42 75 74 20 61 66 74 65 72 0a 2a 2a 20 76 65 But after.** ve
22aa0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 rsion 3.6.23.1,
22ab0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 sqlite3_step() b
22ac0 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b 73 71 egan calling [sq
22ad0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 0a lite3_reset()] .
22ae0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
22af0 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 in this circums
22b00 74 61 6e 63 65 20 72 61 74 68 65 72 20 74 68 61 tance rather tha
22b10 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c n returning [SQL
22b20 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 0a 2a ITE_MISUSE]. .*
22b30 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e *.** <b>Goofy In
22b40 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f terface Alert:</
22b50 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 b> In the legacy
22b60 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 interface, the
22b70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a sqlite3_step().*
22b80 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 * API always ret
22b90 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 urns a generic e
22ba0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 rror code, [SQLI
22bb0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f TE_ERROR], follo
22bc0 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f wing any.** erro
22bd0 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 r other than [SQ
22be0 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b LITE_BUSY] and [
22bf0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 SQLITE_MISUSE].
22c00 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a You must call.*
22c10 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
22c20 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
22c30 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f finalize()] in o
22c40 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 rder to find one
22c50 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 of the.** speci
22c60 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 fic [error codes
22c70 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 ] that better de
22c80 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f scribes the erro
22c90 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 r..** We admit t
22ca0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f hat this is a go
22cb0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 ofy design. The
22cc0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 problem has bee
22cd0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 n fixed.** with
22ce0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
22cf0 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 ce. If you prep
22d00 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 are all of your
22d10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
22d20 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b * using either [
22d30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
22d40 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
22d50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
22d60 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 ] instead.** of
22d70 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 the legacy [sqli
22d80 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
22d90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
22da0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 are16()] interfa
22db0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ces,.** then the
22dc0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b more specific [
22dd0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 error codes] are
22de0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
22df0 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ly.** by sqlite3
22e00 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 _step(). The us
22e10 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e e of the "v2" in
22e20 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d terface is recom
22e30 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 mended..*/.int s
22e40 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 qlite3_step(sqli
22e50 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
22e60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
22e70 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
22e80 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a n a result set.*
22e90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
22ea0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 3_data_count(P)
22eb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
22ec0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 lumns in the.**
22ed0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
22ee0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 t of [prepared s
22ef0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a tatement] P..*/.
22f00 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 int sqlite3_data
22f10 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
22f20 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
22f30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 .** CAPI3REF: Fu
22f40 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 ndamental Dataty
22f50 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a pes.** KEYWORDS:
22f60 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a SQLITE_TEXT.**.
22f70 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 ** ^(Every value
22f80 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f in SQLite has o
22f90 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 ne of five funda
22fa0 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 mental datatypes
22fb0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
22fc0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e <li> 64-bit sign
22fd0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c ed integer.** <l
22fe0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 i> 64-bit IEEE f
22ff0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
23000 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 mber.** <li> str
23010 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 ing.** <li> BLOB
23020 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a .** <li> NULL.**
23030 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 </ul>)^.**.** T
23040 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
23050 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 re codes for eac
23060 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 h of those types
23070 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
23080 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 t the SQLITE_TEX
23090 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 T constant was a
230a0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 lso used in SQLi
230b0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 te version 2.**
230c0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 for a completely
230d0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 different meani
230e0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 ng. Software th
230f0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 at links against
23100 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 both.** SQLite
23110 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 version 2 and SQ
23120 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 Lite version 3 s
23130 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 hould use SQLITE
23140 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 3_TEXT, not.** S
23150 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 QLITE_TEXT..*/.#
23160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
23170 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 TEGER 1.#define
23180 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 SQLITE_FLOAT
23190 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
231a0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 E_BLOB 4.#de
231b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c fine SQLITE_NULL
231c0 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 5.#ifdef SQ
231d0 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 LITE_TEXT.# unde
231e0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 f SQLITE_TEXT.#e
231f0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c lse.# define SQL
23200 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 ITE_TEXT 3.#
23210 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 endif.#define SQ
23220 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 LITE3_TEXT 3
23230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
23240 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 : Result Values
23250 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 From A Query.**
23260 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d KEYWORDS: {colum
23270 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
23280 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ns}.**.** These
23290 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 routines form th
232a0 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 e "result set" i
232b0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
232c0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
232d0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 return informati
232e0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c on about a singl
232f0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 e column of the
23300 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c current.** resul
23310 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 t row of a query
23320 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 . ^In every cas
23330 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 e the first argu
23340 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
23350 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 r.** to the [pre
23360 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
23370 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 that is being e
23380 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 valuated (the [s
23390 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a qlite3_stmt*].**
233a0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e that was return
233b0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
233c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
233d0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 r one of its var
233e0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 iants).** and th
233f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
23400 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f t is the index o
23410 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 f the column for
23420 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 which informati
23430 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 on.** should be
23440 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c returned. ^The l
23450 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f eftmost column o
23460 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
23470 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 has the index 0
23480 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 ..** ^The number
23490 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
234a0 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 he result can be
234b0 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e determined usin
234c0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f g.** [sqlite3_co
234d0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a lumn_count()]..*
234e0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 *.** If the SQL
234f0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
23500 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 ot currently poi
23510 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f nt to a valid ro
23520 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 w, or if the.**
23530 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 column index is
23540 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 out of range, th
23550 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 e result is unde
23560 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 fined..** These
23570 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c routines may onl
23580 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e y be called when
23590 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
235a0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
235b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
235c0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
235d0 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 E_ROW] and neith
235e0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 er.** [sqlite3_r
235f0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c eset()] nor [sql
23600 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
23610 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 have been calle
23620 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a d subsequently..
23630 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 ** If any of the
23640 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
23650 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 called after [sq
23660 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
23670 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 r.** [sqlite3_fi
23680 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 nalize()] or aft
23690 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 er [sqlite3_step
236a0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 ()] has returned
236b0 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 .** something ot
236c0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
236d0 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c _ROW], the resul
236e0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
236f0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 ..** If [sqlite3
23700 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c _step()] or [sql
23710 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
23720 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
23730 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c ze()].** are cal
23740 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 led from a diffe
23750 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c rent thread whil
23760 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 e any of these r
23770 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 outines.** are p
23780 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 ending, then the
23790 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
237a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
237b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
237c0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 n_type() routine
237d0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 returns the.**
237e0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
237f0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d | datatype code]
23800 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c for the initial
23810 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 data type.** of
23820 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 the result colu
23830 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e mn. ^The return
23840 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 ed value is one
23850 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 of [SQLITE_INTEG
23860 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ER],.** [SQLITE_
23870 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f FLOAT], [SQLITE_
23880 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 TEXT], [SQLITE_B
23890 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 LOB], or [SQLITE
238a0 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c _NULL]. The val
238b0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 ue.** returned b
238c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
238d0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 _type() is only
238e0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f meaningful if no
238f0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 type.** convers
23900 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 ions have occurr
23910 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 ed as described
23920 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 below. After a
23930 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c type conversion,
23940 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 .** the value re
23950 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
23960 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 3_column_type()
23970 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 is undefined. F
23980 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e uture.** version
23990 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 s of SQLite may
239a0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 change the behav
239b0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 ior of sqlite3_c
239c0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 olumn_type().**
239d0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 following a type
239e0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a conversion..**.
239f0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
23a00 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 t is a BLOB or U
23a10 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e TF-8 string then
23a20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
23a30 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 umn_bytes().** r
23a40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
23a50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
23a60 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 es in that BLOB
23a70 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 or string..** ^I
23a80 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
23a90 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c a UTF-16 string,
23aa0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
23ab0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e lumn_bytes() con
23ac0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 verts.** the str
23ad0 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 ing to UTF-8 and
23ae0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 then returns th
23af0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
23b00 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 s..** ^If the re
23b10 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 sult is a numeri
23b20 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c c value then sql
23b30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
23b40 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c s() uses.** [sql
23b50 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
23b60 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 to convert that
23b70 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d value to a UTF-
23b80 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 8 string and ret
23b90 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 urns.** the numb
23ba0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
23bb0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e hat string..** ^
23bc0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
23bd0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c ed does not incl
23be0 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 ude the zero ter
23bf0 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 minator at the e
23c00 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 nd.** of the str
23c10 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 ing. ^For clari
23c20 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 ty: the value re
23c30 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 turned is the nu
23c40 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 mber of.** bytes
23c50 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 in the string,
23c60 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f not the number o
23c70 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a f characters..**
23c80 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 .** ^Strings ret
23c90 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
23ca0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 _column_text() a
23cb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
23cc0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 n_text16(),.** e
23cd0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 ven empty string
23ce0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 s, are always ze
23cf0 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro terminated.
23d00 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 ^The return.** v
23d10 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
23d20 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
23d30 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 for a zero-lengt
23d40 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 h BLOB is an arb
23d50 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 itrary.** pointe
23d60 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e r, possibly even
23d70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
23d80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
23d90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
23da0 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 16() routine is
23db0 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 similar to sqlit
23dc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
23dd0 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 ).** but leaves
23de0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 the result in UT
23df0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 F-16 in native b
23e00 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 yte order instea
23e10 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e d of UTF-8..** ^
23e20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 The zero termina
23e30 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 tor is not inclu
23e40 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e ded in this coun
23e50 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 t..**.** ^The ob
23e60 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
23e70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
23e80 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a _value()] is an.
23e90 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 ** [unprotected
23ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
23eb0 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f bject. An unpro
23ec0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
23ed0 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d alue object.** m
23ee0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
23ef0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 with [sqlite3_bi
23f00 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 nd_value()] and
23f10 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
23f20 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 value()]..** If
23f30 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 the [unprotected
23f40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
23f50 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
23f60 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
23f70 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
23f80 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 s used in any ot
23f90 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 her way, includi
23fa0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 ng calls.** to r
23fb0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
23fc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
23fd0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
23fe0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
23ff0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
24000 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 _bytes()], then
24010 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
24020 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
24030 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
24040 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 attempt to conve
24050 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 rt the value whe
24060 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 re appropriate.
24070 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 ^For.** example
24080 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 , if the interna
24090 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e l representation
240a0 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 is FLOAT and a
240b0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 text result.** i
240c0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 s requested, [sq
240d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
240e0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e ] is used intern
240f0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 ally to perform
24100 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f the.** conversio
24110 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e n automatically.
24120 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e ^(The followin
24130 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 g table details
24140 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a the conversions.
24150 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c ** that are appl
24160 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ied:.**.** <bloc
24170 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c kquote>.** <tabl
24180 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a e border="1">.**
24190 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e <tr><th> Intern
241a0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 al<br>Type <th>
241b0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 Requested<br>Typ
241c0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 e <th> Conversi
241d0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 on.**.** <tr><td
241e0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
241f0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 INTEGER <td> R
24200 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 esult is 0.** <t
24210 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
24220 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
24230 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e td> Result is 0.
24240 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
24250 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 ULL <td> TE
24260 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c XT <td> Resul
24270 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 t is NULL pointe
24280 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e r.** <tr><td> N
24290 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c ULL <td> BL
242a0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c OB <td> Resul
242b0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 t is NULL pointe
242c0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e r.** <tr><td> IN
242d0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f TEGER <td> FLO
242e0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 AT <td> Conve
242f0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 rt from integer
24300 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e to float.** <tr>
24310 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
24320 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
24330 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e > ASCII renderin
24340 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 g of the integer
24350 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
24360 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f EGER <td> BLO
24370 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 B <td> Same a
24380 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a s INTEGER->TEXT.
24390 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
243a0 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 AT <td> INTEGE
243b0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 R <td> Convert
243c0 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 from float to i
243d0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 nteger.** <tr><t
243e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
243f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
24400 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 ASCII rendering
24410 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 of the float.**
24420 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
24430 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
24440 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c <td> Same as FL
24450 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 OAT->TEXT.** <tr
24460 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
24470 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
24480 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a d> Use atoi().**
24490 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
244a0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
244b0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 <td> Use atof(
244c0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 ).** <tr><td> T
244d0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c EXT <td> BL
244e0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 OB <td> No ch
244f0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ange.** <tr><td>
24500 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 BLOB <td> I
24510 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f NTEGER <td> Co
24520 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 nvert to TEXT th
24530 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a en use atoi().**
24540 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
24550 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
24560 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 <td> Convert t
24570 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 o TEXT then use
24580 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atof().** <tr><t
24590 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
245a0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
245b0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 Add a zero termi
245c0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a nator if needed.
245d0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c ** </table>.** <
245e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
245f0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 *.** The table a
24600 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 bove makes refer
24610 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 ence to standard
24620 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 C library funct
24630 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 ions atoi().** a
24640 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 nd atof(). SQLi
24650 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c te does not real
24660 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e ly use these fun
24670 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 ctions. It has
24680 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 its.** own equiv
24690 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 alent internal r
246a0 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 outines. The at
246b0 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 oi() and atof()
246c0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 names are.** use
246d0 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 d in the table f
246e0 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 or brevity and b
246f0 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 ecause they are
24700 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 familiar to most
24710 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 .** C programmer
24720 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 s..**.** ^Note t
24730 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f hat when type co
24740 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c nversions occur,
24750 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
24760 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 ed by prior.** c
24770 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
24780 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 column_blob(), s
24790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
247a0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 xt(), and/or.**
247b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
247c0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 ext16() may be i
247d0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 5e nvalidated..** ^
247e0 28 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e (Type conversion
247f0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e s and pointer in
24800 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 validations migh
24810 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 t occur.** in th
24820 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 e following case
24830 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
24840 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 <li> The initia
24850 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 l content is a B
24860 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f LOB and sqlite3_
24870 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 column_text() or
24880 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
24890 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
248a0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a is called. A z
248b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d ero-terminator m
248c0 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 ight.** nee
248d0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f d to be added to
248e0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 the string.</li
248f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
24900 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
24910 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 UTF-8 text and
24920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
24930 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 ytes16() or.**
24940 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
24950 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 mn_text16() is c
24960 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 alled. The cont
24970 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ent must be conv
24980 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f erted.** to
24990 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a UTF-16.</li>.**
249a0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 <li> The initia
249b0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 l content is UTF
249c0 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c -16 text and sql
249d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
249e0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 s() or.** s
249f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
24a00 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 xt() is called.
24a10 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 The content mus
24a20 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a t be converted.*
24a30 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e * to UTF-8.
24a40 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e </li>.** </ul>)^
24a50 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 .**.** ^Conversi
24a60 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d ons between UTF-
24a70 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 16be and UTF-16l
24a80 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e e are always don
24a90 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 e in place and d
24aa0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 o.** not invalid
24ab0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e ate a prior poin
24ac0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 ter, though of c
24ad0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e ourse the conten
24ae0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a t of the buffer.
24af0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f ** that the prio
24b00 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 r pointer points
24b10 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 to will have be
24b20 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 en modified. Ot
24b30 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 her kinds.** of
24b40 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 conversion are d
24b50 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 one in place whe
24b60 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 n it is possible
24b70 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 , but sometimes
24b80 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 they.** are not
24b90 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 possible and in
24ba0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f those cases prio
24bb0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 r pointers are i
24bc0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a nvalidated..**.*
24bd0 2a 20 5e 28 54 68 65 20 73 61 66 65 73 74 20 61 * ^(The safest a
24be0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 nd easiest to re
24bf0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 member policy is
24c00 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 to invoke these
24c10 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 routines.** in
24c20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
24c30 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a wing ways:.**.**
24c40 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 <ul>.** <li>sq
24c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
24c60 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 t() followed by
24c70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
24c80 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
24c90 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
24ca0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 mn_blob() follow
24cb0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
24cc0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
24cd0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
24ce0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
24cf0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
24d00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
24d10 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c es16()</li>.** <
24d20 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 /ul>)^.**.** In
24d30 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
24d40 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
24d50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
24d60 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 (),.** sqlite3_c
24d70 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 olumn_blob(), or
24d80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
24d90 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
24da0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
24db0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 lt.** into the d
24dc0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 esired format, t
24dd0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
24de0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
24df0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
24e00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
24e10 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a to find the siz
24e20 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
24e30 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
24e40 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 ls.** to sqlite3
24e50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
24e60 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
24e70 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c _blob() with cal
24e80 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
24e90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
24ea0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 ), and do not mi
24eb0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
24ec0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
24ed0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 ().** with calls
24ee0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
24ef0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a mn_bytes()..**.*
24f00 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 * ^The pointers
24f10 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
24f20 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
24f30 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
24f40 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
24f50 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
24f60 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
24f70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
24f80 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
24f90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
24fa0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e )] is called. ^
24fb0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 The memory space
24fc0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 used to hold st
24fd0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f rings.** and BLO
24fe0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f Bs is freed auto
24ff0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c matically. Do <
25000 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 b>not</b> pass t
25010 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
25020 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 rned.** [sqlite3
25030 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c _column_blob()],
25040 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
25050 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 _text()], etc. i
25060 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nto.** [sqlite3_
25070 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e free()]..**.** ^
25080 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c (If a memory all
25090 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 ocation error oc
250a0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 curs during the
250b0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e evaluation of an
250c0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f y.** of these ro
250d0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c utines, a defaul
250e0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 t value is retur
250f0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c ned. The defaul
25100 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 t value.** is ei
25110 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 ther the integer
25120 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 0, the floating
25130 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e point number 0.
25140 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 0, or a NULL.**
25150 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 pointer. Subseq
25160 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
25170 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
25180 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a ] will return.**
25190 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
251a0 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 )^.*/.const void
251b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
251c0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
251d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
251e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
251f0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 mn_bytes(sqlite3
25200 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
25210 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
25220 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 olumn_bytes16(sq
25230 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
25240 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 iCol);.double s
25250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f qlite3_column_do
25260 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d uble(sqlite3_stm
25270 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 t*, int iCol);.i
25280 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
25290 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 n_int(sqlite3_st
252a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
252b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
252c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
252d0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
252e0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e , int iCol);.con
252f0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
25300 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
25310 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
25320 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
25330 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
25340 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
25350 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
25360 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 int iCol);.int
25370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
25380 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
25390 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
253a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c lite3_value *sql
253b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
253c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
253d0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a int iCol);../*.
253e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 ** CAPI3REF: Des
253f0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 troy A Prepared
25400 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
25410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
25420 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 te3_finalize() f
25430 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 unction is calle
25440 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 d to delete a [p
25450 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25460 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 t]..** ^If the s
25470 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 tatement was exe
25480 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c cuted successful
25490 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 ly or not execut
254a0 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a ed at all, then.
254b0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 ** SQLITE_OK is
254c0 72 65 74 75 72 6e 65 64 2e 20 5e 49 66 20 65 78 returned. ^If ex
254d0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 ecution of the s
254e0 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 tatement failed
254f0 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f then an.** [erro
25500 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 r code] or [exte
25510 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
25520 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
25530 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
25540 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 e can be called
25550 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 at any point dur
25560 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
25570 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 n of the.** [pre
25580 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
25590 2e 20 20 5e 49 66 20 74 68 65 20 76 69 72 74 75 . ^If the virtu
255a0 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e al machine has n
255b0 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 ot.** completed
255c0 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 execution when t
255d0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 his routine is c
255e0 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c alled, that is l
255f0 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 ike.** encounter
25600 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 ing an error or
25610 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 an [sqlite3_inte
25620 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 rrupt | interrup
25630 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65 t]..** ^Incomple
25640 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 te updates may b
25650 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e e rolled back an
25660 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 d transactions c
25670 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 anceled,.** depe
25680 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 nding on the cir
25690 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 cumstances, and
256a0 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f the.** [error co
256b0 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c de] returned wil
256c0 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f l be [SQLITE_ABO
256d0 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 RT]..*/.int sqli
256e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c te3_finalize(sql
256f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
25700 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
25710 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 EF: Reset A Prep
25720 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
25730 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 bject.**.** The
25740 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 sqlite3_reset()
25750 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c function is call
25760 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 ed to reset a [p
25770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25780 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 t].** object bac
25790 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c k to its initial
257a0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f state, ready to
257b0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e be re-executed.
257c0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 .** ^Any SQL sta
257d0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 tement variables
257e0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 that had values
257f0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 bound to them u
25800 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c sing.** the [sql
25810 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
25820 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
25830 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 ) API] retain th
25840 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 eir values..** U
25850 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 se [sqlite3_clea
25860 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f r_bindings()] to
25870 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 reset the bindi
25880 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ngs..**.** ^The
25890 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
258a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 )] interface res
258b0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 ets the [prepare
258c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a d statement] S.*
258d0 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 * back to the be
258e0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 ginning of its p
258f0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 rogram..**.** ^I
25900 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
25910 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
25920 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 e3_step(S)] for
25930 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
25940 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 statement] S re
25950 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
25960 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 OW] or [SQLITE_D
25970 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b ONE],.** or if [
25980 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
25990 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 has never befor
259a0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e e been called on
259b0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c S,.** then [sql
259c0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
259d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
259e0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 K]..**.** ^If th
259f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
25a00 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
25a10 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a tep(S)] for the.
25a20 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
25a30 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 tement] S indica
25a40 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 ted an error, th
25a50 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 en.** [sqlite3_r
25a60 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 eset(S)] returns
25a70 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
25a80 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a [error code]..**
25a90 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
25aa0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 3_reset(S)] inte
25ab0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 rface does not c
25ac0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 hange the values
25ad0 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 .** of any [sqli
25ae0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 te3_bind_blob|bi
25af0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b ndings] on the [
25b00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25b10 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 nt] S..*/.int sq
25b20 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 lite3_reset(sqli
25b30 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
25b40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
25b50 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 F: Create Or Red
25b60 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 efine SQL Functi
25b70 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ons.** KEYWORDS:
25b80 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 {function creat
25b90 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a ion routines}.**
25ba0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c KEYWORDS: {appl
25bb0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
25bc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a SQL function}.**
25bd0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c KEYWORDS: {appl
25be0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
25bf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a SQL functions}.*
25c00 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74 77 6f 20 *.** ^These two
25c10 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 functions (colle
25c20 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 ctively known as
25c30 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 "function creat
25c40 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a ion routines").*
25c50 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 * are used to ad
25c60 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 d SQL functions
25c70 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 or aggregates or
25c80 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 to redefine the
25c90 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 behavior.** of
25ca0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e existing SQL fun
25cb0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
25cc0 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 ates. The only
25cd0 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 difference betwe
25ce0 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 en the.** two is
25cf0 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 that the second
25d00 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 parameter, the
25d10 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 name of the (sca
25d20 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 lar) function or
25d30 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 .** aggregate, i
25d40 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 s encoded in UTF
25d50 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 -8 for sqlite3_c
25d60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
25d70 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 and UTF-16.** f
25d80 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
25d90 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a e_function16()..
25da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
25db0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
25dc0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
25dd0 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 ection] to which
25de0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 the SQL.** func
25df0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 tion is to be ad
25e00 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 ded. ^If an app
25e10 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f lication uses mo
25e20 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 re than one data
25e30 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
25e40 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 on then applicat
25e50 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
25e60 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 functions must b
25e70 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 e added.** to ea
25e80 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ch database conn
25e90 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c ection separatel
25ea0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 y..**.** The sec
25eb0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
25ec0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
25ed0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f SQL function to
25ee0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a be created or.*
25ef0 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 * redefined. ^T
25f00 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
25f10 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 name is limited
25f20 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 to 255 bytes, e
25f30 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 xclusive of.** t
25f40 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 he zero-terminat
25f50 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 or. Note that t
25f60 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c he name length l
25f70 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 imit is in bytes
25f80 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 , not.** charact
25f90 65 72 73 2e 20 20 5e 41 6e 79 20 61 74 74 65 6d ers. ^Any attem
25fa0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 pt to create a f
25fb0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c unction with a l
25fc0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 onger name.** wi
25fd0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 ll result in [SQ
25fe0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e LITE_ERROR] bein
25ff0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a g returned..**.*
26000 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 * ^The third par
26010 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a ameter (nArg).**
26020 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
26030 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 f arguments that
26040 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
26050 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
26060 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 e takes. ^If thi
26070 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d s parameter is -
26080 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 1, then the SQL
26090 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
260a0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b ggregate may tak
260b0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 e any number of
260c0 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 arguments betwee
260d0 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 n 0 and the limi
260e0 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c t.** set by [sql
260f0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c ite3_limit]([SQL
26100 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
26110 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 ON_ARG]). If th
26120 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d e third.** param
26130 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 eter is less tha
26140 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 n -1 or greater
26150 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 than 127 then th
26160 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a e behavior is.**
26170 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
26180 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 * The fourth par
26190 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 ameter, eTextRep
261a0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 , specifies what
261b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
261c0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
261d0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
261e0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
261f0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
26200 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 s. Any SQL func
26210 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
26220 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 ion should be ab
26230 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f le to work.** wo
26240 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 rk with UTF-8, U
26250 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d TF-16le, or UTF-
26260 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 16be. But some
26270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
26280 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 may be.** more e
26290 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e fficient with on
262a0 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 e encoding than
262b0 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 another. ^An ap
262c0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a plication may.**
262d0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
262e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
262f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 ) or sqlite3_cre
26300 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
26310 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d multiple.** tim
26320 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 es with the same
26330 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 function but wi
26340 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c th different val
26350 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e ues of eTextRep.
26360 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 .** ^When multip
26370 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
26380 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 ns of the same f
26390 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 unction are avai
263a0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a lable, SQLite.**
263b0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f will pick the o
263c0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 ne that involves
263d0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e the least amoun
263e0 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 t of data conver
263f0 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 sion..** If ther
26400 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 e is only a sing
26410 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
26420 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 n which does not
26430 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a care what text.
26440 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 ** encoding is u
26450 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f sed, then the fo
26460 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 urth argument sh
26470 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f ould be [SQLITE_
26480 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ANY]..**.** ^(Th
26490 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 e fifth paramete
264a0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 r is an arbitrar
264b0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 y pointer. The
264c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
264d0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f f the.** functio
264e0 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 n can gain acces
264f0 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 s to this pointe
26500 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 r using [sqlite3
26510 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e _user_data()].)^
26520 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e .**.** The seven
26530 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e th, eighth and n
26540 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c inth parameters,
26550 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e xFunc, xStep an
26560 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a d xFinal, are.**
26570 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c pointers to C-l
26580 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e anguage function
26590 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
265a0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
265b0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
265c0 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c e. ^A scalar SQL
265d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
265e0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 es an implementa
265f0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e tion of the xFun
26600 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e c.** callback on
26610 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 ly; NULL pointer
26620 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 s should be pass
26630 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 ed as the xStep
26640 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 and xFinal.** pa
26650 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 rameters. ^An ag
26660 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
26670 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
26680 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
26690 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 of xStep.** and
266a0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 xFinal and NULL
266b0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 should be passed
266c0 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 for xFunc. ^To
266d0 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 delete an existi
266e0 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 ng.** SQL functi
266f0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c on or aggregate,
26700 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 pass NULL for a
26710 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f ll three functio
26720 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a n callbacks..**.
26730 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 ** ^It is permit
26740 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 ted to register
26750 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
26760 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
26770 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e same.** function
26780 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
26790 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 name but with ei
267a0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e ther differing n
267b0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 umbers of.** arg
267c0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 uments or differ
267d0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 ing preferred te
267e0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e xt encodings. ^
267f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a SQLite will use.
26800 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ** the implement
26810 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 ation that most
26820 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 closely matches
26830 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 the way in which
26840 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 the.** SQL func
26850 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e tion is used. ^
26860 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 A function imple
26870 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 mentation with a
26880 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a non-negative.**
26890 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 nArg parameter
268a0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 is a better matc
268b0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
268c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
268d0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 with.** a negat
268e0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 ive nArg. ^A fu
268f0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
26900 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
26910 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 encoding.** matc
26920 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 hes the database
26930 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 encoding is a b
26940 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 etter.** match t
26950 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 han a function w
26960 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
26970 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 g is different.
26980 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e .** ^A function
26990 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
269a0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
269b0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c s between UTF16l
269c0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a e and UTF16be.**
269d0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 is a closer mat
269e0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
269f0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 on where the enc
26a00 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 oding difference
26a10 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 is.** between U
26a20 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a TF8 and UTF16..*
26a30 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 *.** ^Built-in f
26a40 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 unctions may be
26a50 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 overloaded by ne
26a60 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 w application-de
26a70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e fined functions.
26a80 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
26a90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
26aa0 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ed function with
26ab0 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 a given name ov
26ac0 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 errides all.** b
26ad0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e uilt-in function
26ae0 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 s in the same [d
26af0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
26b00 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d on] with the sam
26b10 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73 e name..** ^Subs
26b20 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69 equent applicati
26b30 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
26b40 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
26b50 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 name only overr
26b60 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 ide .** prior ap
26b70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
26b80 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 d functions that
26b90 20 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61 are an exact ma
26ba0 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e tch for the.** n
26bb0 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 umber of paramet
26bc0 65 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65 ers and preferre
26bd0 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a d encoding..**.*
26be0 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f * ^An applicatio
26bf0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
26c00 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 on is permitted
26c10 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a to call other.**
26c20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
26c30 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 es. However, su
26c40 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f ch calls must no
26c50 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 t.** close the d
26c60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
26c70 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 on nor finalize
26c80 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 or reset the pre
26c90 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
26ca0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 nt in which the
26cb0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
26cc0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ing..*/.int sqli
26cd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
26ce0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ion(. sqlite3 *
26cf0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 db,. const char
26d00 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c *zFunctionName,
26d10 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 . int nArg,. i
26d20 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 nt eTextRep,. v
26d30 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 oid *pApp,. voi
26d40 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
26d50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
26d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
26d70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
26d80 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
26d90 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
26da0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
26db0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
26dc0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 3_context*).);.i
26dd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
26de0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 e_function16(.
26df0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
26e00 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 onst void *zFunc
26e10 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
26e20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
26e30 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
26e40 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
26e50 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
26e60 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
26e70 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
26e80 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
26e90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
26ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
26eb0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
26ec0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
26ed0 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 xt*).);../*.** C
26ee0 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e API3REF: Text En
26ef0 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 codings.**.** Th
26f00 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 ese constant def
26f10 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 ine integer code
26f20 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 s that represent
26f30 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 the various.**
26f40 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 text encodings s
26f50 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 upported by SQLi
26f60 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
26f70 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 QLITE_UTF8
26f80 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
26f90 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 QLITE_UTF16LE
26fa0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
26fb0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 QLITE_UTF16BE
26fc0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
26fd0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 QLITE_UTF16
26fe0 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 4 /* Use
26ff0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
27000 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 er */.#define SQ
27010 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 LITE_ANY
27020 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 5 /* sqli
27030 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
27040 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 ion only */.#def
27050 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
27060 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f _ALIGNED 8 /
27070 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
27080 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 _collation only
27090 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
270a0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 EF: Deprecated F
270b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 unctions.** DEPR
270c0 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 ECATED.**.** The
270d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
270e0 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 [deprecated].
270f0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e In order to main
27100 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 tain.** backward
27110 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
27120 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c with older code,
27130 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
27140 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f continue .** to
27150 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 be supported.
27160 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 However, new app
27170 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
27180 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 avoid.** the us
27190 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 e of these funct
271a0 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 ions. To help e
271b0 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 ncourage people
271c0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e to avoid.** usin
271d0 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e g these function
271e0 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f s, we are not go
271f0 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 ing to tell you
27200 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f what they do..*/
27210 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
27220 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a OMIT_DEPRECATED.
27230 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
27240 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 D int sqlite3_ag
27250 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 gregate_count(sq
27260 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
27270 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 .SQLITE_DEPRECAT
27280 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 ED int sqlite3_e
27290 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 xpired(sqlite3_s
272a0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 tmt*);.SQLITE_DE
272b0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
272c0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 ite3_transfer_bi
272d0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 ndings(sqlite3_s
272e0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 tmt*, sqlite3_st
272f0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 mt*);.SQLITE_DEP
27300 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
27310 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 te3_global_recov
27320 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 er(void);.SQLITE
27330 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 _DEPRECATED void
27340 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f sqlite3_thread_
27350 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 cleanup(void);.S
27360 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
27370 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d int sqlite3_mem
27380 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a ory_alarm(void(*
27390 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f )(void*,sqlite3_
273a0 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a int64,int),void*
273b0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b ,sqlite3_int64);
273c0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
273d0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 API3REF: Obtaini
273e0 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 ng SQL Function
273f0 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 Parameter Values
27400 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e .**.** The C-lan
27410 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 guage implementa
27420 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 tion of SQL func
27430 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 tions and aggreg
27440 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 ates uses.** thi
27450 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 s set of interfa
27460 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 ce routines to a
27470 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 ccess the parame
27480 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a ter values on.**
27490 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 the function or
274a0 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a aggregate..**.*
274b0 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 * The xFunc (for
274c0 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e scalar function
274d0 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 s) or xStep (for
274e0 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 aggregates) par
274f0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 ameters.** to [s
27500 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
27510 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 nction()] and [s
27520 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
27530 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 nction16()].** d
27540 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 efine callbacks
27550 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 that implement t
27560 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 he SQL functions
27570 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e and aggregates.
27580 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 .** The 4th para
27590 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 meter to these c
275a0 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 allbacks is an a
275b0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
275c0 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 to.** [protecte
275d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
275e0 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 objects. There
275f0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 is one [sqlite3
27600 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 _value] object f
27610 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d or.** each param
27620 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 eter to the SQL
27630 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 function. These
27640 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
27650 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 ed to.** extract
27660 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 values from the
27670 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
27680 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 objects..**.**
27690 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 These routines w
276a0 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 ork only with [p
276b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
276c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
276d0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 .** Any attempt
276e0 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 to use these rou
276f0 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 tines on an [unp
27700 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
27710 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 _value].** objec
27720 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 t results in und
27730 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e efined behavior.
27740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
27750 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 utines work just
27760 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 like the corres
27770 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 ponding [column
27780 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 access functions
27790 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 ].** except that
277a0 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 these routines
277b0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b take a single [
277c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
277d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 3_value] object.
277e0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 ** pointer inste
277f0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 ad of a [sqlite3
27800 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 _stmt*] pointer
27810 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 and an integer c
27820 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a olumn number..**
27830 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
27840 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 _value_text16()
27850 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 interface extrac
27860 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 ts a UTF-16 stri
27870 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 ng.** in the nat
27880 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f ive byte-order o
27890 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 f the host machi
278a0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c ne. ^The.** sql
278b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
278c0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 6be() and sqlite
278d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
278e0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
278f0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 extract UTF-16
27900 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 strings as big-e
27910 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 ndian and little
27920 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 -endian respecti
27930 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 vely..**.** ^(Th
27940 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
27950 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 numeric_type() i
27960 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 nterface attempt
27970 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 s to apply.** nu
27980 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 meric affinity t
27990 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 o the value. Th
279a0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e is means that an
279b0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d attempt is.** m
279c0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ade to convert t
279d0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 he value to an i
279e0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 nteger or floati
279f0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a ng point. If.**
27a00 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 such a conversi
27a10 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 on is possible w
27a20 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 ithout loss of i
27a30 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f nformation (in o
27a40 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 ther.** words, i
27a50 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 f the value is a
27a60 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f string that loo
27a70 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 ks like a number
27a80 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f ).** then the co
27a90 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 nversion is perf
27aa0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 ormed. Otherwis
27ab0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 e no conversion
27ac0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b occurs..** The [
27ad0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
27ae0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 datatype] after
27af0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 conversion is r
27b00 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a eturned.)^.**.**
27b10 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 Please pay part
27b20 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e icular attention
27b30 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 to the fact tha
27b40 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 t the pointer re
27b50 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b turned.** from [
27b60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
27b70 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ob()], [sqlite3_
27b80 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f value_text()], o
27b90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 r.** [sqlite3_va
27ba0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 lue_text16()] ca
27bb0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 n be invalidated
27bc0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 by a subsequent
27bd0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
27be0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
27bf0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
27c00 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 lue_bytes16()],
27c10 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
27c20 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 ext()],.** or [s
27c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
27c40 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 t16()]..**.** Th
27c50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 ese routines mus
27c60 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
27c70 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
27c80 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 as.** the SQL f
27c90 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 unction that sup
27ca0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 plied the [sqlit
27cb0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d e3_value*] param
27cc0 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 eters..*/.const
27cd0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
27ce0 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 lue_blob(sqlite3
27cf0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
27d00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
27d10 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a s(sqlite3_value*
27d20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
27d30 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c alue_bytes16(sql
27d40 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f ite3_value*);.do
27d50 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c uble sqlite3_val
27d60 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 ue_double(sqlite
27d70 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 3_value*);.int s
27d80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
27d90 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
27da0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 ;.sqlite3_int64
27db0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e sqlite3_value_in
27dc0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 t64(sqlite3_valu
27dd0 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 e*);.const unsig
27de0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 ned char *sqlite
27df0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 3_value_text(sql
27e00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f ite3_value*);.co
27e10 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
27e20 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 3_value_text16(s
27e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
27e40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
27e50 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
27e60 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le(sqlite3_value
27e70 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a *);.const void *
27e80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
27e90 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 xt16be(sqlite3_v
27ea0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
27eb0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 te3_value_type(s
27ec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
27ed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
27ee0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 e_numeric_type(s
27ef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
27f00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
27f10 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 Obtain Aggregat
27f20 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 e Function Conte
27f30 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 xt.**.** Impleme
27f40 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 ntions of aggreg
27f50 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
27f60 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f s use this.** ro
27f70 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 utine to allocat
27f80 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f e memory for sto
27f90 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 ring their state
27fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
27fb0 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 st time the sqli
27fc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
27fd0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 ntext(C,N) routi
27fe0 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a ne is called .**
27ff0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
28000 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 r aggregate func
28010 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 tion, SQLite.**
28020 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d allocates N of m
28030 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 emory, zeroes ou
28040 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 t that memory, a
28050 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 nd returns a poi
28060 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e nter.** to the n
28070 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 ew memory. ^On s
28080 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
28090 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a uent calls to.**
280a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
280b0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 te_context() for
280c0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 the same aggreg
280d0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 ate function ins
280e0 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 tance,.** the sa
280f0 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 me buffer is ret
28100 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f urned. Sqlite3_
28110 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
28120 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a t() is normally.
28130 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 ** called once f
28140 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 or each invocati
28150 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 on of the xStep
28160 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 callback and the
28170 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 n one.** last ti
28180 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e me when the xFin
28190 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 al callback is i
281a0 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 nvoked. ^(When
281b0 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a no rows match.**
281c0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 an aggregate qu
281d0 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 ery, the xStep()
281e0 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 callback of the
281f0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
28200 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ion.** implement
28210 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 ation is never c
28220 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c alled and xFinal
28230 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 () is called exa
28240 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e ctly once..** In
28250 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 those cases, sq
28260 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
28270 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 context() might
28280 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 be called for th
28290 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 e.** first time
282a0 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e from within xFin
282b0 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 al().)^.**.** ^T
282c0 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 he sqlite3_aggre
282d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e gate_context(C,N
282e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
282f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
28300 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 if N is.** less
28310 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 than or equal t
28320 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d o zero or if a m
28330 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 emory allocate e
28340 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a rror occurs..**.
28350 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 ** ^(The amount
28360 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 of space allocat
28370 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 ed by sqlite3_ag
28380 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
28390 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 C,N) is.** deter
283a0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 mined by the N p
283b0 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 arameter on firs
283c0 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c t successful cal
283d0 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 l. Changing the
283e0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 .** value of N i
283f0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c n subsequent cal
28400 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 l to sqlite3_agg
28410 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
28420 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 within.** the s
28430 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 ame aggregate fu
28440 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 nction instance
28450 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 will not resize
28460 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c the memory.** al
28470 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a location.)^.**.*
28480 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 * ^SQLite automa
28490 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 tically frees th
284a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
284b0 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 ed by .** sqlite
284c0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
284d0 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 ext() when the a
284e0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 ggregate query c
284f0 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 oncludes..**.**
28500 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
28510 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f ter must be a co
28520 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 py of the.** [sq
28530 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 lite3_context |
28540 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e SQL function con
28550 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 text] that is th
28560 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
28570 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 r.** to the xSte
28580 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c p or xFinal call
28590 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 back routine tha
285a0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 t implements the
285b0 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 aggregate.** fu
285c0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 nction..**.** Th
285d0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
285e0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
285f0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
28600 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
28610 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e ggregate SQL fun
28620 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
28630 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
28640 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
28650 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
28660 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 text*, int nByte
28670 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
28680 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 REF: User Data F
28690 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a or Functions.**.
286a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
286b0 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 user_data() inte
286c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
286d0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 copy of.** the p
286e0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 ointer that was
286f0 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 the pUserData pa
28700 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 rameter (the 5th
28710 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f parameter).** o
28720 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
28730 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
28740 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
28750 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
28760 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 n16()] routines
28770 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a that originally.
28780 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 ** registered th
28790 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 e application de
287a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a fined function..
287b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
287c0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ne must be calle
287d0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
287e0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
287f0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
28800 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
28810 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
28820 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
28830 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 _user_data(sqlit
28840 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f e3_context*);../
28850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
28860 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
28870 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 on For Functions
28880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
28890 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
288a0 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 andle() interfac
288b0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
288c0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 of.** the point
288d0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 er to the [datab
288e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
288f0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 (the 1st paramet
28900 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
28910 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
28920 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
28930 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
28940 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
28950 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
28960 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
28970 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
28980 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
28990 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 nction..*/.sqlit
289a0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 e3 *sqlite3_cont
289b0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 ext_db_handle(sq
289c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
289d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
289e0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c : Function Auxil
289f0 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 iary Data.**.**
28a00 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 The following tw
28a10 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 o functions may
28a20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 be used by scala
28a30 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 r SQL functions
28a40 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 to.** associate
28a50 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 metadata with ar
28a60 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 gument values. I
28a70 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 f the same value
28a80 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a is passed to.**
28a90 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 multiple invoca
28aa0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
28ab0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 e SQL function d
28ac0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 uring query exec
28ad0 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 ution, under.**
28ae0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 some circumstanc
28af0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 es the associate
28b00 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 d metadata may b
28b10 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 e preserved. Thi
28b20 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 s may.** be used
28b30 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 , for example, t
28b40 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d o add a regular-
28b50 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 expression match
28b60 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 ing scalar.** fu
28b70 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 nction. The comp
28b80 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 iled version of
28b90 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
28ba0 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 ession is stored
28bb0 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 as.** metadata
28bc0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
28bd0 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 the SQL value pa
28be0 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 ssed as the regu
28bf0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a lar expression.*
28c00 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 * pattern. The
28c10 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 compiled regular
28c20 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 expression can
28c30 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c be reused on mul
28c40 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 tiple.** invocat
28c50 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
28c60 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 function so tha
28c70 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 t the original p
28c80 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a attern string.**
28c90 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
28ca0 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 o be recompiled
28cb0 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 on each invocati
28cc0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 on..**.** ^The s
28cd0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
28ce0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ta() interface r
28cf0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
28d00 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 to the metadata
28d10 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 .** associated b
28d20 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 y the sqlite3_se
28d30 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 t_auxdata() func
28d40 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 tion with the Nt
28d50 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 h argument.** va
28d60 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 lue to the appli
28d70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
28d80 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 unction. ^If no
28d90 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 metadata has bee
28da0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 n ever.** been s
28db0 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 et for the Nth a
28dc0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 rgument of the f
28dd0 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 unction, or if t
28de0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
28df0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
28e00 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 ameter has chang
28e10 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 ed since the met
28e20 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a a-data was set,.
28e30 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ** then sqlite3_
28e40 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 get_auxdata() re
28e50 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
28e60 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nter..**.** ^The
28e70 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
28e80 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
28e90 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 saves the metad
28ea0 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 ata.** pointed t
28eb0 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 o by its 3rd par
28ec0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 ameter as the me
28ed0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e tadata for the N
28ee0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 -th.** argument
28ef0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
28f00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
28f10 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 ion. Subsequent
28f20 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c .** calls to sql
28f30 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
28f40 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 () might return
28f50 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 this data, if it
28f60 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e has.** not been
28f70 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e destroyed..** ^
28f80 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c If it is not NUL
28f90 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 L, SQLite will i
28fa0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 nvoke the destru
28fb0 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ctor.** function
28fc0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 given by the 4t
28fd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
28fe0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
28ff0 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d ta() on.** the m
29000 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 etadata when the
29010 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 corresponding f
29020 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 unction paramete
29030 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 r changes.** or
29040 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 when the SQL sta
29050 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 tement completes
29060 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 , whichever come
29070 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 s first..**.** S
29080 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f QLite is free to
29090 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 call the destru
290a0 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 ctor and drop me
290b0 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a tadata on any.**
290c0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e parameter of an
290d0 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e y function at an
290e0 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e y time. ^The on
290f0 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 ly guarantee is
29100 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 that.** the dest
29110 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 ructor will be c
29120 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 alled before the
29130 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f metadata is dro
29140 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e pped..**.** ^(In
29150 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 practice, metad
29160 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 ata is preserved
29170 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f between functio
29180 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 n calls for.** e
29190 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 xpressions that
291a0 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 are constant at
291b0 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 compile time. Th
291c0 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 is includes lite
291d0 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e ral.** values an
291e0 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 d [parameters].)
291f0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ^.**.** These ro
29200 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 utines must be c
29210 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
29220 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 ame thread in wh
29230 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 ich.** the SQL f
29240 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
29250 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c ng..*/.void *sql
29260 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
29270 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29280 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 *, int N);.void
29290 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
292a0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
292b0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 ext*, int N, voi
292c0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 d*, void (*)(voi
292d0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 d*));.../*.** CA
292e0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 PI3REF: Constant
292f0 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 s Defining Speci
29300 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 al Destructor Be
29310 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 havior.**.** The
29320 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 se are special v
29330 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 alues for the de
29340 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 structor that is
29350 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 passed in as th
29360 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d e.** final argum
29370 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 ent to routines
29380 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 like [sqlite3_re
29390 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e sult_blob()]. ^
293a0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f If the destructo
293b0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 r.** argument is
293c0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 SQLITE_STATIC,
293d0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 it means that th
293e0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 e content pointe
293f0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a r is constant.**
29400 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 and will never
29410 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 change. It does
29420 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
29430 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 destroyed. ^The
29440 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 .** SQLITE_TRANS
29450 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 IENT value means
29460 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
29470 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 t will likely ch
29480 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e ange in.** the n
29490 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 ear future and t
294a0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c hat SQLite shoul
294b0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 d make its own p
294c0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a rivate copy of.*
294d0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 * the content be
294e0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a fore returning..
294f0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 **.** The typede
29500 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 f is necessary t
29510 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 o work around pr
29520 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 oblems in certai
29530 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 n.** C++ compile
29540 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 rs. See ticket
29550 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 #2191..*/.typede
29560 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 f void (*sqlite3
29570 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 _destructor_type
29580 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e )(void*);.#defin
29590 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 e SQLITE_STATIC
295a0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 ((sqlite3_d
295b0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 estructor_type)0
295c0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
295d0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 _TRANSIENT ((s
295e0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
295f0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a r_type)-1)../*.*
29600 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 * CAPI3REF: Sett
29610 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f ing The Result O
29620 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f f An SQL Functio
29630 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f n.**.** These ro
29640 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 utines are used
29650 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 by the xFunc or
29660 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 xFinal callbacks
29670 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 that.** impleme
29680 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 nt SQL functions
29690 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e and aggregates.
296a0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 See.** [sqlite
296b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
296c0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 n()] and [sqlite
296d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
296e0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 n16()].** for ad
296f0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
29700 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tion..**.** Thes
29710 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b e functions work
29720 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 very much like
29730 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 the [parameter b
29740 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f inding] family o
29750 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 f.** functions u
29760 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 sed to bind valu
29770 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d es to host param
29780 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 eters in prepare
29790 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a d statements..**
297a0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 Refer to the [S
297b0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f QL parameter] do
297c0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
297d0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
297e0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 mation..**.** ^T
297f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
29800 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 t_blob() interfa
29810 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
29820 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 lt from.** an ap
29830 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
29840 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
29850 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 the BLOB whose
29860 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 content is point
29870 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 ed.** to by the
29880 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
29890 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 and which is N
298a0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 bytes long where
298b0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 N is the.** thi
298c0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a rd parameter..**
298d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
298e0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 _result_zeroblob
298f0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 () interfaces se
29900 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a t the result of.
29910 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
29920 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
29930 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 ion to be a BLOB
29940 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 containing all
29950 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e zero.** bytes an
29960 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a d N bytes in siz
29970 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 e, where N is th
29980 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 e value of the 2
29990 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a nd parameter..**
299a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
299b0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 _result_double()
299c0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
299d0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
299e0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
299f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
29a00 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 on to be a float
29a10 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 ing point value
29a20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 specified.** by
29a30 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 its 2nd argument
29a40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
29a50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
29a60 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f r() and sqlite3_
29a70 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
29a80 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 functions.** ca
29a90 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e use the implemen
29aa0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ted SQL function
29ab0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 to throw an exc
29ac0 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 eption..** ^SQLi
29ad0 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 te uses the stri
29ae0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ng pointed to by
29af0 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 the.** 2nd para
29b00 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 meter of sqlite3
29b10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
29b20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
29b30 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 t_error16().** a
29b40 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e s the text of an
29b50 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 error message.
29b60 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 ^SQLite interpr
29b70 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a ets the error.**
29b80 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
29b90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 from sqlite3_res
29ba0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 ult_error() as U
29bb0 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a TF-8. ^SQLite.**
29bc0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 interprets the
29bd0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 string from sqli
29be0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
29bf0 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 16() as UTF-16 i
29c00 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 n native.** byte
29c10 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 order. ^If the
29c20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
29c30 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
29c40 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 lt_error().** or
29c50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
29c60 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 error16() is neg
29c70 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 ative then SQLit
29c80 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 e takes as the e
29c90 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
29ca0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f all text up thro
29cb0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 ugh the first ze
29cc0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a ro character..**
29cd0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 ^If the third p
29ce0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
29cf0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
29d00 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
29d10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
29d20 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 ) is non-negativ
29d30 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 e then SQLite ta
29d40 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a kes that many.**
29d50 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 bytes (not char
29d60 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 acters) from the
29d70 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
29d80 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 s the error mess
29d90 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c age..** ^The sql
29da0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
29db0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f r() and sqlite3_
29dc0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
29dd0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b .** routines mak
29de0 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 e a private copy
29df0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 of the error me
29e00 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 ssage text befor
29e10 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e e.** they return
29e20 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 . Hence, the ca
29e30 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 lling function c
29e40 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 an deallocate or
29e50 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 .** modify the t
29e60 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 ext after they r
29e70 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 eturn without ha
29e80 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 rm..** ^The sqli
29e90 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
29ea0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e _code() function
29eb0 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 changes the err
29ec0 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 or code.** retur
29ed0 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 ned by SQLite as
29ee0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 a result of an
29ef0 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 error in a funct
29f00 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c ion. ^By defaul
29f10 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 t,.** the error
29f20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 code is SQLITE_E
29f30 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 RROR. ^A subseq
29f40 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c uent call to sql
29f50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
29f60 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 r().** or sqlite
29f70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
29f80 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 () resets the er
29f90 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 ror code to SQLI
29fa0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 TE_ERROR..**.**
29fb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
29fc0 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 ult_toobig() int
29fd0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 erface causes SQ
29fe0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e Lite to throw an
29ff0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 error.** indica
2a000 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 ting that a stri
2a010 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f ng or BLOB is to
2a020 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 o long to repres
2a030 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ent..**.** ^The
2a040 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
2a050 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 omem() interface
2a060 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 causes SQLite t
2a070 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 o throw an error
2a080 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 .** indicating t
2a090 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c hat a memory all
2a0a0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a ocation failed..
2a0b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2a0c0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 e3_result_int()
2a0d0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
2a0e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
2a0f0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
2a100 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
2a110 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
2a120 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 32-bit signed i
2a130 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 nteger.** value
2a140 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 given in the 2nd
2a150 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 argument..** ^T
2a160 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
2a170 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 t_int64() interf
2a180 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
2a190 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
2a1a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
2a1b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
2a1c0 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 to be the 64-bi
2a1d0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
2a1e0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 .** value given
2a1f0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d in the 2nd argum
2a200 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ent..**.** ^The
2a210 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
2a220 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 ull() interface
2a230 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 sets the return
2a240 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 value.** of the
2a250 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2a260 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
2a270 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e be NULL..**.** ^
2a280 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
2a290 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 lt_text(), sqlit
2a2a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
2a2b0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 (),.** sqlite3_r
2a2c0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 esult_text16le()
2a2d0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 , and sqlite3_re
2a2e0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 sult_text16be()
2a2f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 interfaces.** se
2a300 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c t the return val
2a310 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ue of the applic
2a320 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
2a330 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 nction to be.**
2a340 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 a text string wh
2a350 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 ich is represent
2a360 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 ed as UTF-8, UTF
2a370 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 -16 native byte
2a380 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 order,.** UTF-16
2a390 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 little endian,
2a3a0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e or UTF-16 big en
2a3b0 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 dian, respective
2a3c0 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 ly..** ^SQLite t
2a3d0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 akes the text re
2a3e0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 sult from the ap
2a3f0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a plication from.*
2a400 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 * the 2nd parame
2a410 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ter of the sqlit
2a420 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
2a430 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e interfaces..** ^
2a440 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
2a450 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
2a460 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
2a470 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
2a480 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
2a490 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 SQLite takes re
2a4a0 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 sult text from t
2a4b0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
2a4c0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 .** through the
2a4d0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 first zero chara
2a4e0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 cter..** ^If the
2a4f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
2a500 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
2a510 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
2a520 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d faces.** is non-
2a530 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 negative, then a
2a540 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f s many bytes (no
2a550 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 t characters) of
2a560 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 the text.** poi
2a570 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 nted to by the 2
2a580 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 nd parameter are
2a590 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 taken as the ap
2a5a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2a5b0 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 d.** function re
2a5c0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 sult..** ^If the
2a5d0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
2a5e0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
2a5f0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
2a600 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 faces.** or sqli
2a610 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
2a620 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f is a non-NULL po
2a630 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 inter, then SQLi
2a640 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a te calls that.**
2a650 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 function as the
2a660 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 destructor on t
2a670 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
2a680 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 result when it h
2a690 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 as.** finished u
2a6a0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 sing that result
2a6b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 ..** ^If the 4th
2a6c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
2a6d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2a6e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
2a6f0 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 s or to.** sqlit
2a700 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 e3_result_blob i
2a710 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f s the special co
2a720 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 nstant SQLITE_ST
2a730 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 ATIC, then SQLit
2a740 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 e.** assumes tha
2a750 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c t the text or BL
2a760 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 OB result is in
2a770 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 constant space a
2a780 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 nd does not.** c
2a790 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 opy the content
2a7a0 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 of the parameter
2a7b0 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 nor call a dest
2a7c0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f ructor on the co
2a7d0 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 ntent.** when it
2a7e0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 has finished us
2a7f0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e ing that result.
2a800 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 .** ^If the 4th
2a810 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
2a820 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2a830 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
2a840 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
2a850 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 esult_blob is th
2a860 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 e special consta
2a870 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 nt SQLITE_TRANSI
2a880 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 ENT.** then SQLi
2a890 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 te makes a copy
2a8a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e of the result in
2a8b0 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 to space obtaine
2a8c0 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b d from.** from [
2a8d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
2a8e0 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 ] before it retu
2a8f0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rns..**.** ^The
2a900 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
2a910 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 alue() interface
2a920 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
2a930 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
2a940 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
2a950 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 unction to be a
2a960 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 copy the.** [unp
2a970 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2a980 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 _value] object s
2a990 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
2a9a0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 2nd parameter.
2a9b0 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ^The.** sqlite3_
2a9c0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 result_value() i
2a9d0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 nterface makes a
2a9e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 copy of the [sq
2a9f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
2aa00 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c so that the [sql
2aa10 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 ite3_value] spec
2aa20 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 ified in the par
2aa30 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 ameter may chang
2aa40 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c e or.** be deall
2aa50 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c ocated after sql
2aa60 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
2aa70 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 e() returns with
2aa80 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 out harm..** ^A
2aa90 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
2aaa0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2aab0 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 may always be u
2aac0 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 sed where an.**
2aad0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
2aae0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
2aaf0 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 ct is required,
2ab00 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e so either.** kin
2ab10 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 d of [sqlite3_va
2ab20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 lue] object can
2ab30 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 be used with thi
2ab40 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a s interface..**.
2ab50 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 ** If these rout
2ab60 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
2ab70 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
2ab80 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
2ab90 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 .** than the one
2aba0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
2abb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2abc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ned function tha
2abd0 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 t received.** th
2abe0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 e [sqlite3_conte
2abf0 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 xt] pointer, the
2ac00 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
2ac10 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 efined..*/.void
2ac20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
2ac30 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 lob(sqlite3_cont
2ac40 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
2ac50 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 *, int, void(*)(
2ac60 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 void*));.void sq
2ac70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 lite3_result_dou
2ac80 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ble(sqlite3_cont
2ac90 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 ext*, double);.v
2aca0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
2acb0 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 lt_error(sqlite3
2acc0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
2acd0 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f char*, int);.vo
2ace0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
2acf0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 t_error16(sqlite
2ad00 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
2ad10 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 t void*, int);.v
2ad20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
2ad30 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 lt_error_toobig(
2ad40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2ad50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
2ad60 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d result_error_nom
2ad70 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 em(sqlite3_conte
2ad80 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 xt*);.void sqlit
2ad90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
2ada0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e code(sqlite3_con
2adb0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 text*, int);.voi
2adc0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
2add0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e _int(sqlite3_con
2ade0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 text*, int);.voi
2adf0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
2ae00 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 _int64(sqlite3_c
2ae10 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 ontext*, sqlite3
2ae20 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 _int64);.void sq
2ae30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c lite3_result_nul
2ae40 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 l(sqlite3_contex
2ae50 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 t*);.void sqlite
2ae60 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 3_result_text(sq
2ae70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
2ae80 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
2ae90 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
2aea0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
2aeb0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 result_text16(sq
2aec0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
2aed0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
2aee0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
2aef0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
2af00 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
2af10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2af20 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
2af30 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a nt,void(*)(void*
2af40 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
2af50 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 _result_text16be
2af60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2af70 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
2af80 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
2af90 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
2afa0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 3_result_value(s
2afb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2afc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 sqlite3_value*)
2afd0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
2afe0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 esult_zeroblob(s
2aff0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2b000 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int n);../*.**
2b010 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 CAPI3REF: Define
2b020 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 New Collating S
2b030 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 equences.**.** T
2b040 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
2b050 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e re used to add n
2b060 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ew collation seq
2b070 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a uences to the.**
2b080 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2b090 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 ction] specified
2b0a0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
2b0b0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gument..**.** ^T
2b0c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e he name of the n
2b0d0 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ew collation seq
2b0e0 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 uence is specifi
2b0f0 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 ed as a UTF-8 st
2b100 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 ring.** for sqli
2b110 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
2b120 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 tion() and sqlit
2b130 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
2b140 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 ion_v2().** and
2b150 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 a UTF-16 string
2b160 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
2b170 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 te_collation16()
2b180 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a . ^In all cases.
2b190 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 ** the name is p
2b1a0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
2b1b0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
2b1c0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ument..**.** ^Th
2b1d0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
2b1e0 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 may be one of t
2b1f0 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 he constants [SQ
2b200 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b LITE_UTF8],.** [
2b210 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c SQLITE_UTF16LE],
2b220 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
2b230 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 6BE], indicating
2b240 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 that the user-s
2b250 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 upplied.** routi
2b260 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 ne expects to be
2b270 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 passed pointers
2b280 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f to strings enco
2b290 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c ded using UTF-8,
2b2a0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c .** UTF-16 littl
2b2b0 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 e-endian, or UTF
2b2c0 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 -16 big-endian,
2b2d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e 54 respectively. ^T
2b2e0 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 he.** third argu
2b2f0 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 ment might also
2b300 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 be [SQLITE_UTF16
2b310 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 ] to indicate th
2b320 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a at the routine.*
2b330 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 * expects pointe
2b340 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36 20 rs to be UTF-16
2b350 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 6e strings in the n
2b360 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
2b370 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 , or the.** argu
2b380 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51 4c ment can be [SQL
2b390 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 ITE_UTF16_ALIGNE
2b3a0 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 D] if the.** the
2b3b0 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 routine expects
2b3c0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d pointers to 16-
2b3d0 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 bit word aligned
2b3e0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 strings.** of U
2b3f0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
2b400 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
2b410 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 **.** A pointer
2b420 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 to the user supp
2b430 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 lied routine mus
2b440 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 t be passed as t
2b450 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 he fifth.** argu
2b460 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69 73 ment. ^If it is
2b470 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 NULL, this is t
2b480 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 he same as delet
2b490 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f ing the collatio
2b4a0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 n.** sequence (s
2b4b0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 o that SQLite ca
2b4c0 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 nnot call it any
2b4d0 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 more)..** ^Each
2b4e0 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 time the applica
2b4f0 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 tion supplied fu
2b500 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 nction is invoke
2b510 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a d, it is passed.
2b520 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 ** as its first
2b530 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 parameter a copy
2b540 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 of the void* pa
2b550 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 ssed as the four
2b560 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 th argument.** t
2b570 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 o sqlite3_create
2b580 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 _collation() or
2b590 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
2b5a0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a ollation16()..**
2b5b0 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e 69 .** ^The remaini
2b5c0 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 ng arguments to
2b5d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
2b5e0 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 supplied routine
2b5f0 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 are two strings
2b600 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 ,.** each repres
2b610 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 ented by a (leng
2b620 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 th, data) pair a
2b630 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 nd encoded in th
2b640 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 e encoding.** th
2b650 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 at was passed as
2b660 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
2b670 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c ent when the col
2b680 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 lation sequence
2b690 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 was.** registere
2b6a0 64 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 d. The applicat
2b6b0 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c ion defined coll
2b6c0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 ation routine sh
2b6d0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e ould.** return n
2b6e0 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 egative, zero or
2b6f0 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 positive if the
2b700 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 first string is
2b710 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 less than,.** e
2b720 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 qual to, or grea
2b730 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 ter than the sec
2b740 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e ond string. i.e.
2b750 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 (STRING1 - STRI
2b760 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NG2)..**.** ^The
2b770 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2b780 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 collation_v2() w
2b790 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 orks like sqlite
2b7a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2b7b0 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 on().** except t
2b7c0 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 hat it takes an
2b7d0 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 extra argument w
2b7e0 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 hich is a destru
2b7f0 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 ctor for.** the
2b800 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65 collation. ^The
2b810 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 destructor is c
2b820 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 alled when the c
2b830 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 ollation is.** d
2b840 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 estroyed and is
2b850 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 passed a copy of
2b860 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
2b870 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e meter void* poin
2b880 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 ter.** of the sq
2b890 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
2b8a0 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 lation_v2()..**
2b8b0 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 ^Collations are
2b8c0 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 destroyed when t
2b8d0 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 hey are overridd
2b8e0 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c en by later call
2b8f0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c s to the.** coll
2b900 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 ation creation f
2b910 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e unctions or when
2b920 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2b930 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c onnection] is cl
2b940 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 osed.** using [s
2b950 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e qlite3_close()].
2b960 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2b970 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 [sqlite3_colla
2b980 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 tion_needed()] a
2b990 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c nd [sqlite3_coll
2b9a0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
2b9b0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
2b9c0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2b9d0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 on(. sqlite3*,
2b9e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2b9f0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 Name, . int eTe
2ba00 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c xtRep, . void*,
2ba10 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
2ba20 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
2ba30 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
2ba40 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 t void*).);.int
2ba50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
2ba60 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 ollation_v2(. s
2ba70 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 qlite3*, . cons
2ba80 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a t char *zName, .
2ba90 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
2baa0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 . void*,. int(
2bab0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
2bac0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
2bad0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
2bae0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 ),. void(*xDest
2baf0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 roy)(void*).);.i
2bb00 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
2bb10 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 e_collation16(.
2bb20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
2bb30 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c nst void *zName,
2bb40 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
2bb50 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 . void*,. int
2bb60 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 (*xCompare)(void
2bb70 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
2bb80 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
2bb90 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *).);../*.** CAP
2bba0 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e I3REF: Collation
2bbb0 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b Needed Callback
2bbc0 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 s.**.** ^To avoi
2bbd0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 d having to regi
2bbe0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 ster all collati
2bbf0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 on sequences bef
2bc00 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a ore a database.*
2bc10 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 * can be used, a
2bc20 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b single callback
2bc30 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 function may be
2bc40 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 registered with
2bc50 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
2bc60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f e connection] to
2bc70 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
2bc80 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 ever an undefine
2bc90 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 d collation.** s
2bca0 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 equence is requi
2bcb0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 red..**.** ^If t
2bcc0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 he function is r
2bcd0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 egistered using
2bce0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c the sqlite3_coll
2bcf0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 ation_needed() A
2bd00 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 PI,.** then it i
2bd10 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d s passed the nam
2bd20 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 es of undefined
2bd30 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
2bd40 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a ces as strings.*
2bd50 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 * encoded in UTF
2bd60 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f -8. ^If sqlite3_
2bd70 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
2bd80 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 16() is used,.**
2bd90 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 the names are p
2bda0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 assed as UTF-16
2bdb0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 in machine nativ
2bdc0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
2bdd0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 ^A call to eith
2bde0 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c er function repl
2bdf0 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e aces the existin
2be00 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 g collation-need
2be10 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a ed callback..**.
2be20 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 ** ^(When the ca
2be30 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
2be40 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 d, the first arg
2be50 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 ument passed is
2be60 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 a copy.** of the
2be70 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
2be80 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c to sqlite3_coll
2be90 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f ation_needed() o
2bea0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
2beb0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
2bec0 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 ). The second a
2bed0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 rgument is the d
2bee0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
2bef0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 ction. The thir
2bf00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e d argument is on
2bf10 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 e of [SQLITE_UTF
2bf20 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 8], [SQLITE_UTF1
2bf30 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 6BE],.** or [SQL
2bf40 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e ITE_UTF16LE], in
2bf50 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 dicating the mos
2bf60 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d t desirable form
2bf70 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f of the collatio
2bf80 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 n.** sequence fu
2bf90 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e nction required.
2bfa0 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 The fourth par
2bfb0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 ameter is the na
2bfc0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 me of the.** req
2bfd0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 uired collation
2bfe0 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a sequence.)^.**.*
2bff0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
2c000 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 unction should r
2c010 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 egister the desi
2c020 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 red collation us
2c030 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
2c040 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
2c050 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
2c060 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
2c070 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
2c080 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
2c090 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 tion_v2()]..*/.i
2c0a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 nt sqlite3_colla
2c0b0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 tion_needed(. s
2c0c0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 qlite3*, . void
2c0d0 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f *, . void(*)(vo
2c0e0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 id*,sqlite3*,int
2c0f0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 eTextRep,const
2c100 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 char*).);.int sq
2c110 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
2c120 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 needed16(. sqli
2c130 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a te3*, . void*,.
2c140 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c void(*)(void*,
2c150 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 sqlite3*,int eTe
2c160 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 xtRep,const void
2c170 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 *).);..#ifdef SQ
2c180 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f LITE_HAS_CODEC./
2c190 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 *.** Specify the
2c1a0 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 key for an encr
2c1b0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 ypted database.
2c1c0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 This routine sh
2c1d0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 ould be.** calle
2c1e0 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 d right after sq
2c1f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a lite3_open()..**
2c200 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 .** The code to
2c210 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 implement this A
2c220 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 PI is not availa
2c230 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 ble in the publi
2c240 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 c release.** of
2c250 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 SQLite..*/.int s
2c260 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 qlite3_key(. sq
2c270 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
2c280 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2c290 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 Database to be r
2c2a0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 ekeyed */. cons
2c2b0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e t void *pKey, in
2c2c0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 t nKey /* Th
2c2d0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a e key */.);../*.
2c2e0 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 ** Change the ke
2c2f0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 y on an open dat
2c300 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 abase. If the c
2c310 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 urrent database
2c320 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 is not.** encryp
2c330 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e ted, this routin
2c340 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 e will encrypt i
2c350 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f t. If pNew==0 o
2c360 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a r nNew==0, the.*
2c370 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 * database is de
2c380 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 crypted..**.** T
2c390 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 he code to imple
2c3a0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 ment this API is
2c3b0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 not available i
2c3c0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c n the public rel
2c3d0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ease.** of SQLit
2c3e0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
2c3f0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 3_rekey(. sqlit
2c400 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2c410 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
2c420 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 abase to be reke
2c430 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 yed */. const v
2c440 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e oid *pKey, int n
2c450 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e Key /* The n
2c460 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a ew key */.);../*
2c470 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 .** Specify the
2c480 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 activation key f
2c490 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 or a SEE databas
2c4a0 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 e. Unless .** a
2c4b0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f ctivated, none o
2c4c0 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e f the SEE routin
2c4d0 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f es will work..*/
2c4e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 .void sqlite3_ac
2c4f0 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f tivate_see(. co
2c500 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 nst char *zPassP
2c510 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 hrase /*
2c520 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 Activation phras
2c530 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a e */.);.#endif..
2c540 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e #ifdef SQLITE_EN
2c550 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a ABLE_CEROD./*.**
2c560 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 Specify the act
2c570 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 ivation key for
2c580 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 a CEROD database
2c590 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 . Unless .** ac
2c5a0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 tivated, none of
2c5b0 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 the CEROD routi
2c5c0 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a nes will work..*
2c5d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 /.void sqlite3_a
2c5e0 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 ctivate_cerod(.
2c5f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 const char *zPa
2c600 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 ssPhrase
2c610 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 /* Activation ph
2c620 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 rase */.);.#endi
2c630 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
2c640 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 F: Suspend Execu
2c650 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 tion For A Short
2c660 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 Time.**.** ^The
2c670 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 sqlite3_sleep()
2c680 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 function causes
2c690 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 the current thr
2c6a0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 ead to suspend e
2c6b0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 xecution.** for
2c6c0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 at least a numbe
2c6d0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
2c6e0 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 s specified in i
2c6f0 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ts parameter..**
2c700 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 65 72 .** ^If the oper
2c710 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 ating system doe
2c720 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c s not support sl
2c730 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 eep requests wit
2c740 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 h.** millisecond
2c750 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e time resolution
2c760 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 , then the time
2c770 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 will be rounded
2c780 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 up to.** the nea
2c790 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 5e 54 68 rest second. ^Th
2c7a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c e number of mill
2c7b0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
2c7c0 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 p actually.** re
2c7d0 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 quested from the
2c7e0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
2c7f0 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a m is returned..*
2c800 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 *.** ^SQLite imp
2c810 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 lements this int
2c820 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e erface by callin
2c830 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a g the xSleep().*
2c840 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 * method of the
2c850 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
2c860 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f _vfs] object..*/
2c870 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 .int sqlite3_sle
2c880 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ep(int);../*.**
2c890 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f CAPI3REF: Name O
2c8a0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c f The Folder Hol
2c8b0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 ding Temporary F
2c8c0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 iles.**.** ^(If
2c8d0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 this global vari
2c8e0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 able is made to
2c8f0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e point to a strin
2c900 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 g which is.** th
2c910 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 e name of a fold
2c920 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 er (a.k.a. direc
2c930 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 tory), then all
2c940 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a temporary files.
2c950 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 ** created by SQ
2c960 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 Lite when using
2c970 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 a built-in [sqli
2c980 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a te3_vfs | VFS].*
2c990 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 * will be placed
2c9a0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f in that directo
2c9b0 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 ry.)^ ^If this
2c9c0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 variable.** is a
2c9d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 NULL pointer, t
2c9e0 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f hen SQLite perfo
2c9f0 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 rms a search for
2ca00 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a an appropriate.
2ca10 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c ** temporary fil
2ca20 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a e directory..**.
2ca30 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 ** It is not saf
2ca40 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 e to read or mod
2ca50 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c ify this variabl
2ca60 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f e in more than o
2ca70 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 ne.** thread at
2ca80 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e a time. It is n
2ca90 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 ot safe to read
2caa0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 or modify this v
2cab0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 ariable.** if a
2cac0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2cad0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 tion] is being u
2cae0 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 sed at the same
2caf0 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 time in a separa
2cb00 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a te.** thread..**
2cb10 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 It is intended
2cb20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
2cb30 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a le be set once.*
2cb40 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f * as part of pro
2cb50 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 cess initializat
2cb60 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 ion and before a
2cb70 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ny SQLite interf
2cb80 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ace.** routines
2cb90 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 have been called
2cba0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 and that this v
2cbb0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 ariable remain u
2cbc0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 nchanged.** ther
2cbd0 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 eafter..**.** ^T
2cbe0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
2cbf0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
2cc00 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 may modify this
2cc10 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 variable and ca
2cc20 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 use.** it to poi
2cc30 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 nt to memory obt
2cc40 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
2cc50 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 te3_malloc]. ^F
2cc60 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 urthermore,.** t
2cc70 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
2cc80 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
2cc90 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 always assumes
2cca0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a that any string.
2ccb0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 ** that this var
2ccc0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 iable points to
2ccd0 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 is held in memor
2cce0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
2ccf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
2cd00 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 loc] and the pra
2cd10 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 gma may attempt
2cd20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d to free that mem
2cd30 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 ory.** using [sq
2cd40 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 lite3_free]..**
2cd50 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 Hence, if this v
2cd60 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 ariable is modif
2cd70 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 ied directly, ei
2cd80 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 ther it should b
2cd90 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f e.** made NULL o
2cda0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 r made to point
2cdb0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
2cdc0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
2cdd0 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 _malloc].** or e
2cde0 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 lse the use of t
2cdf0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
2ce00 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
2ce10 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 should be avoid
2ce20 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 ed..*/.SQLITE_EX
2ce30 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 TERN char *sqlit
2ce40 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 e3_temp_director
2ce50 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 y;../*.** CAPI3R
2ce60 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 EF: Test For Aut
2ce70 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a o-Commit Mode.**
2ce80 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f KEYWORDS: {auto
2ce90 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a commit mode}.**.
2cea0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2ceb0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 get_autocommit()
2cec0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2ced0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a ns non-zero or.*
2cee0 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 * zero if the gi
2cef0 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e ven database con
2cf00 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 nection is or is
2cf10 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d not in autocomm
2cf20 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 it mode,.** resp
2cf30 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f ectively. ^Auto
2cf40 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f commit mode is o
2cf50 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a n by default..**
2cf60 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 ^Autocommit mod
2cf70 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 e is disabled by
2cf80 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 a [BEGIN] state
2cf90 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f ment..** ^Autoco
2cfa0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d mmit mode is re-
2cfb0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f enabled by a [CO
2cfc0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 MMIT] or [ROLLBA
2cfd0 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 CK]..**.** If ce
2cfe0 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 rtain kinds of e
2cff0 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 rrors occur on a
2d000 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
2d010 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d n a multi-statem
2d020 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 ent.** transacti
2d030 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 on (errors inclu
2d040 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c ding [SQLITE_FUL
2d050 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 L], [SQLITE_IOER
2d060 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e R],.** [SQLITE_N
2d070 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 OMEM], [SQLITE_B
2d080 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 USY], and [SQLIT
2d090 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 E_INTERRUPT]) th
2d0a0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 en the.** transa
2d0b0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 ction might be r
2d0c0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
2d0d0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f atically. The o
2d0e0 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 nly way to.** fi
2d0f0 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 nd out whether S
2d100 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 QLite automatica
2d110 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 lly rolled back
2d120 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
2d130 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f after.** an erro
2d140 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 r is to use this
2d150 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
2d160 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 If another thre
2d170 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 ad changes the a
2d180 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 utocommit status
2d190 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2d1a0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 .** connection w
2d1b0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e hile this routin
2d1c0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 e is running, th
2d1d0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
2d1e0 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 lue.** is undefi
2d1f0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ned..*/.int sqli
2d200 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d te3_get_autocomm
2d210 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f it(sqlite3*);../
2d220 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
2d230 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 ind The Database
2d240 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 Handle Of A Pre
2d250 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a pared Statement.
2d260 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2d270 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 e3_db_handle int
2d280 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
2d290 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
2d2a0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a nection] handle.
2d2b0 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 ** to which a [p
2d2c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d2d0 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 t] belongs. ^Th
2d2e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2d2f0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 ection].** retur
2d300 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 ned by sqlite3_d
2d310 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 b_handle is the
2d320 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
2d330 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 onnection].** th
2d340 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 at was the first
2d350 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
2d360 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
2d370 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 pare_v2()] call
2d380 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 (or its variants
2d390 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 ) that was used
2d3a0 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 to.** create the
2d3b0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
2d3c0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
2d3d0 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 /.sqlite3 *sqlit
2d3e0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c e3_db_handle(sql
2d3f0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
2d400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 .** CAPI3REF: Fi
2d410 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 nd the next prep
2d420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
2d430 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 *.** ^This inter
2d440 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
2d450 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 ointer to the ne
2d460 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 xt [prepared sta
2d470 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a tement] after.**
2d480 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 pStmt associate
2d490 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 d with the [data
2d4a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2d4b0 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 pDb. ^If pStmt
2d4c0 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e is NULL.** then
2d4d0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
2d4e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
2d4f0 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 r to the first p
2d500 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d510 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 t.** associated
2d520 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 with the databas
2d530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 e connection pDb
2d540 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 . ^If no prepar
2d550 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
2d560 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f satisfies the co
2d570 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 nditions of this
2d580 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 routine, it ret
2d590 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a urns NULL..**.**
2d5a0 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 The [database c
2d5b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 onnection] point
2d5c0 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 er D in a call t
2d5d0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 o.** [sqlite3_ne
2d5e0 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 xt_stmt(D,S)] mu
2d5f0 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f st refer to an o
2d600 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 pen database.**
2d610 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 connection and i
2d620 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 n particular mus
2d630 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 t not be a NULL
2d640 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 pointer..*/.sqli
2d650 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 te3_stmt *sqlite
2d660 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 3_next_stmt(sqli
2d670 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 te3 *pDb, sqlite
2d680 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
2d690 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2d6a0 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c Commit And Roll
2d6b0 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f back Notificatio
2d6c0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a n Callbacks.**.*
2d6d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
2d6e0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 ommit_hook() int
2d6f0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
2d700 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 a callback.** f
2d710 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e unction to be in
2d720 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
2d730 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
2d740 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 [COMMIT | commit
2d750 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 ted]..** ^Any ca
2d760 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 llback set by a
2d770 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
2d780 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f sqlite3_commit_
2d790 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 hook().** for th
2d7a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
2d7b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 connection is ov
2d7c0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 erridden..** ^Th
2d7d0 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 e sqlite3_rollba
2d7e0 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 ck_hook() interf
2d7f0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
2d800 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 callback.** func
2d810 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b tion to be invok
2d820 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 ed whenever a tr
2d830 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f ansaction is [RO
2d840 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 LLBACK | rolled
2d850 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 back]..** ^Any c
2d860 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 allback set by a
2d870 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2d880 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 o sqlite3_rollba
2d890 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 ck_hook().** for
2d8a0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2d8b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2d8c0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 overridden..**
2d8d0 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 ^The pArg argume
2d8e0 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 nt is passed thr
2d8f0 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c ough to the call
2d900 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 back..** ^If the
2d910 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 callback on a c
2d920 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 ommit hook funct
2d930 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ion returns non-
2d940 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 zero,.** then th
2d950 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 e commit is conv
2d960 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c erted into a rol
2d970 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 lback..**.** ^Th
2d980 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 e sqlite3_commit
2d990 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 _hook(D,C,P) and
2d9a0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 sqlite3_rollbac
2d9b0 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 k_hook(D,C,P) fu
2d9c0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 nctions.** retur
2d9d0 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 n the P argument
2d9e0 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f from the previo
2d9f0 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 us call of the s
2da00 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ame function.**
2da10 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 on the same [dat
2da20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2da30 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 ] D, or NULL for
2da40 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 .** the first ca
2da50 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 ll for each func
2da60 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a tion on D..**.**
2da70 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d The callback im
2da80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 plementation mus
2da90 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
2daa0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
2dab0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
2dac0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
2dad0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 at invoked the c
2dae0 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 allback. Any ac
2daf0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 tions.** to modi
2db00 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 fy the database
2db10 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 connection must
2db20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 be deferred unti
2db30 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 l after the.** c
2db40 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 ompletion of the
2db50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2db60 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 ] call that trig
2db70 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 gered the commit
2db80 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 .** or rollback
2db90 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 hook in the firs
2dba0 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 t place..** Note
2dbb0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
2dbc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
2dbd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2dbe0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
2dbf0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
2dc00 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
2dc10 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
2dc20 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
2dc30 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
2dc40 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 ^Registering a
2dc50 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 NULL function di
2dc60 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 sables the callb
2dc70 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e ack..**.** ^When
2dc80 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b the commit hook
2dc90 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e callback routin
2dca0 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 e returns zero,
2dcb0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 the [COMMIT].**
2dcc0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c operation is all
2dcd0 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 owed to continue
2dce0 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 normally. ^If
2dcf0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a the commit hook.
2dd00 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ** returns non-z
2dd10 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 ero, then the [C
2dd20 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 OMMIT] is conver
2dd30 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c ted into a [ROLL
2dd40 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 BACK]..** ^The r
2dd50 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 ollback hook is
2dd60 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c invoked on a rol
2dd70 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c lback that resul
2dd80 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 ts from a commit
2dd90 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 .** hook returni
2dda0 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 ng non-zero, jus
2ddb0 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 t as it would be
2ddc0 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 with any other
2ddd0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 rollback..**.**
2dde0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 ^For the purpose
2ddf0 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 s of this API, a
2de00 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
2de10 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 said to have bee
2de20 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b n.** rolled back
2de30 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 if an explicit
2de40 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 "ROLLBACK" state
2de50 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 ment is executed
2de60 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 , or.** an error
2de70 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 or constraint c
2de80 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 auses an implici
2de90 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 t rollback to oc
2dea0 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c cur..** ^The rol
2deb0 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 lback callback i
2dec0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 s not invoked if
2ded0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
2dee0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c s.** automatical
2def0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 ly rolled back b
2df00 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 ecause the datab
2df10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
2df20 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 s closed..**.**
2df30 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 See also the [sq
2df40 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
2df50 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a k()] interface..
2df60 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
2df70 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c _commit_hook(sql
2df80 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f ite3*, int(*)(vo
2df90 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f id*), void*);.vo
2dfa0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c id *sqlite3_roll
2dfb0 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 back_hook(sqlite
2dfc0 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 3*, void(*)(void
2dfd0 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a *), void*);../*
2dfe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
2dff0 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 ta Change Notifi
2e000 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 cation Callbacks
2e010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2e020 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
2e030 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
2e040 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
2e050 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 function.** wit
2e060 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
2e070 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e connection] iden
2e080 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 tified by the fi
2e090 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 rst argument.**
2e0a0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 to be invoked wh
2e0b0 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 enever a row is
2e0c0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 updated, inserte
2e0d0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a d or deleted..**
2e0e0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 ^Any callback s
2e0f0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 et by a previous
2e100 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 call to this fu
2e110 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 nction.** for th
2e120 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
2e130 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 connection is ov
2e140 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 erridden..**.**
2e150 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
2e160 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
2e170 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f r to the functio
2e180 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e n to invoke when
2e190 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 a.** row is upd
2e1a0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f ated, inserted o
2e1b0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 r deleted..** ^T
2e1c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2e1d0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 t to the callbac
2e1e0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 k is a copy of t
2e1f0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
2e200 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f t.** to sqlite3_
2e210 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a update_hook()..*
2e220 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61 * ^The second ca
2e230 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 llback argument
2e240 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 is one of [SQLIT
2e250 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 E_INSERT], [SQLI
2e260 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f TE_DELETE],.** o
2e270 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 r [SQLITE_UPDATE
2e280 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ], depending on
2e290 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 the operation th
2e2a0 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 at caused the ca
2e2b0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 llback.** to be
2e2c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 invoked..** ^The
2e2d0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
2e2e0 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 h arguments to t
2e2f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 he callback cont
2e300 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 ain pointers to
2e310 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
2e320 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 and table name c
2e330 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 ontaining the af
2e340 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e fected row..** ^
2e350 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 The final callba
2e360 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 ck parameter is
2e370 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 the [rowid] of t
2e380 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 he row..** ^In t
2e390 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 he case of an up
2e3a0 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 date, this is th
2e3b0 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 e [rowid] after
2e3c0 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 the update takes
2e3d0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 place..**.** ^(
2e3e0 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 The update hook
2e3f0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 is not invoked w
2e400 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 hen internal sys
2e410 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a tem tables are.*
2e420 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e * modified (i.e.
2e430 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 sqlite_master a
2e440 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e nd sqlite_sequen
2e450 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e ce).)^.**.** ^In
2e460 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 the current imp
2e470 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 lementation, the
2e480 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 update hook.**
2e490 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 is not invoked w
2e4a0 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 hen duplication
2e4b0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 rows are deleted
2e4c0 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a because of an.*
2e4d0 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c * [ON CONFLICT |
2e4e0 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 ON CONFLICT REP
2e4f0 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e LACE] clause. ^
2e500 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74 Nor is the updat
2e510 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 e hook.** invoke
2e520 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 d when rows are
2e530 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 deleted using th
2e540 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 e [truncate opti
2e550 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 mization]..** Th
2e560 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 e exceptions def
2e570 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 ined in this par
2e580 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 agraph might cha
2e590 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a nge in a future.
2e5a0 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 ** release of SQ
2e5b0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
2e5c0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c update hook impl
2e5d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 ementation must
2e5e0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 not do anything
2e5f0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 that will modify
2e600 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
2e610 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
2e620 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 invoked the upd
2e630 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 ate hook. Any a
2e640 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 ctions.** to mod
2e650 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 ify the database
2e660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 connection must
2e670 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 be deferred unt
2e680 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 il after the.**
2e690 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 completion of th
2e6a0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
2e6b0 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 )] call that tri
2e6c0 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74 ggered the updat
2e6d0 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 e hook..** Note
2e6e0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
2e6f0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
2e700 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2e710 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
2e720 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
2e730 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
2e740 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
2e750 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
2e760 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
2e770 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 ^The sqlite3_upd
2e780 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 ate_hook(D,C,P)
2e790 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 function.** retu
2e7a0 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 rns the P argume
2e7b0 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 nt from the prev
2e7c0 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 ious call.** on
2e7d0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
2e7e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
2e7f0 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a , or NULL for.**
2e800 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 the first call
2e810 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 on D..**.** See
2e820 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 also the [sqlite
2e830 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 3_commit_hook()]
2e840 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f and [sqlite3_ro
2e850 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a llback_hook()].*
2e860 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f * interfaces..*/
2e870 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 .void *sqlite3_u
2e880 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 pdate_hook(. sq
2e890 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 lite3*, . void(
2e8a0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 *)(void *,int ,c
2e8b0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 har const *,char
2e8c0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 const *,sqlite3
2e8d0 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a _int64),. void*
2e8e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
2e8f0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
2e900 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 isable Shared Pa
2e910 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 ger Cache.** KEY
2e920 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 WORDS: {shared c
2e930 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ache}.**.** ^(Th
2e940 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c is routine enabl
2e950 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
2e960 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 he sharing of th
2e970 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 e database cache
2e980 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 .** and schema d
2e990 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 ata structures b
2e9a0 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 etween [database
2e9b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f connection | co
2e9c0 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f nnections].** to
2e9d0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2e9e0 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 se. Sharing is e
2e9f0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 nabled if the ar
2ea00 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a gument is true.*
2ea10 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 * and disabled i
2ea20 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 f the argument i
2ea30 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a s false.)^.**.**
2ea40 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 ^Cache sharing
2ea50 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 is enabled and d
2ea60 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 isabled for an e
2ea70 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a ntire process..*
2ea80 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e * This is a chan
2ea90 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 ge as of SQLite
2eaa0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 version 3.5.0. I
2eab0 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 n prior versions
2eac0 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 of SQLite,.** s
2ead0 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c haring was enabl
2eae0 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 ed or disabled f
2eaf0 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73 or each thread s
2eb00 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a eparately..**.**
2eb10 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61 ^(The cache sha
2eb20 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 ring mode set by
2eb30 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
2eb40 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 effects all subs
2eb50 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 equent.** calls
2eb60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
2eb70 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
2eb80 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 en_v2()], and [s
2eb90 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
2eba0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 ..** Existing da
2ebb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2ebc0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 ns continue use
2ebd0 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 the sharing mode
2ebe0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 .** that was in
2ebf0 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 effect at the ti
2ec00 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 me they were ope
2ec10 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ned.)^.**.** ^(T
2ec20 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
2ec30 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
2ec40 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 if shared cache
2ec50 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 was enabled or d
2ec60 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 isabled.** succe
2ec70 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 ssfully. An [er
2ec80 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
2ec90 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e urned otherwise.
2eca0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 )^.**.** ^Shared
2ecb0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c cache is disabl
2ecc0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 ed by default. B
2ecd0 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 ut this might ch
2ece0 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 ange in.** futur
2ecf0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
2ed00 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 Lite. Applicati
2ed10 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62 ons that care ab
2ed20 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 out shared.** ca
2ed30 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 che setting shou
2ed40 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 ld set it explic
2ed50 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 itly..**.** See
2ed60 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 Also: [SQLite S
2ed70 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 hared-Cache Mode
2ed80 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
2ed90 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
2eda0 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a ache(int);../*.*
2edb0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 * CAPI3REF: Atte
2edc0 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 mpt To Free Heap
2edd0 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 Memory.**.** ^T
2ede0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 he sqlite3_relea
2edf0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 se_memory() inte
2ee00 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
2ee10 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a o free N bytes.*
2ee20 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 * of heap memory
2ee30 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 by deallocating
2ee40 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d non-essential m
2ee50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
2ee60 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 s.** held by the
2ee70 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 database librar
2ee80 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 y. Memory used
2ee90 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 to cache databa
2eea0 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 se.** pages to i
2eeb0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e mprove performan
2eec0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 ce is an example
2eed0 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 of non-essentia
2eee0 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 l memory..** ^sq
2eef0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 lite3_release_me
2ef00 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 mory() returns t
2ef10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2ef20 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 es actually free
2ef30 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 d,.** which migh
2ef40 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 t be more or les
2ef50 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e s than the amoun
2ef60 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a t requested..*/.
2ef70 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 int sqlite3_rele
2ef80 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b ase_memory(int);
2ef90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2efa0 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 : Impose A Limit
2efb0 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a On Heap Size.**
2efc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2efd0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
2efe0 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 () interface pla
2eff0 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d ces a "soft" lim
2f000 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f it.** on the amo
2f010 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f unt of heap memo
2f020 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 ry that may be a
2f030 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 llocated by SQLi
2f040 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 69 6e te..** ^If an in
2f050 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f ternal allocatio
2f060 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 74 n is requested t
2f070 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 hat would exceed
2f080 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 the.** soft hea
2f090 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 p limit, [sqlite
2f0a0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
2f0b0 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ()] is invoked o
2f0c0 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 ne or.** more ti
2f0d0 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 mes to free up s
2f0e0 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 ome space before
2f0f0 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 the allocation
2f100 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a is performed..**
2f110 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69 74 20 69 .** ^The limit i
2f120 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 20 s called "soft"
2f130 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 because if [sqli
2f140 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2f150 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 ry()].** cannot
2f160 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 free sufficient
2f170 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e memory to preven
2f180 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d t the limit from
2f190 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c being exceeded,
2f1a0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 .** the memory i
2f1b0 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 s allocated anyw
2f1c0 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 ay and the curre
2f1d0 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f nt operation pro
2f1e0 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 ceeds..**.** ^A
2f1f0 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f negative or zero
2f200 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 value for N mea
2f210 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 ns that there is
2f220 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 no soft heap li
2f230 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 mit and.** [sqli
2f240 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2f250 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 ry()] will only
2f260 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d be called when m
2f270 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 emory is exhaust
2f280 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 ed..** ^The defa
2f290 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 ult value for th
2f2a0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
2f2b0 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a t is zero..**.**
2f2c0 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ^(SQLite makes
2f2d0 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f a best effort to
2f2e0 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 honor the soft
2f2f0 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 heap limit..** B
2f300 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 ut if the soft h
2f310 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 eap limit cannot
2f320 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 be honored, exe
2f330 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 cution will.** c
2f340 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 ontinue without
2f350 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 error or notific
2f360 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69 73 20 69 ation.)^ This i
2f370 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 s why the limit
2f380 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 is.** called a "
2f390 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 soft" limit. It
2f3a0 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c is advisory onl
2f3b0 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 y..**.** Prior t
2f3c0 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e o SQLite version
2f3d0 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 3.5.0, this rou
2f3e0 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 tine only constr
2f3f0 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 ained the memory
2f400 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 .** allocated by
2f410 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 a single thread
2f420 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 - the same thre
2f430 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 ad in which this
2f440 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 routine.** runs
2f450 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 . Beginning wit
2f460 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e h SQLite version
2f470 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 3.5.0, the soft
2f480 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a heap limit is.*
2f490 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c * applied to all
2f4a0 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 threads. The va
2f4b0 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f lue specified fo
2f4c0 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 r the soft heap
2f4d0 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 limit.** is an u
2f4e0 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 pper bound on th
2f4f0 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 e total memory a
2f500 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c llocation for al
2f510 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a l threads. In.**
2f520 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 version 3.5.0 t
2f530 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 here is no mecha
2f540 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e nism for limitin
2f550 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 g the heap usage
2f560 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 for.** individu
2f570 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 al threads..*/.v
2f580 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 oid sqlite3_soft
2f590 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 _heap_limit(int)
2f5a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2f5b0 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 F: Extract Metad
2f5c0 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 ata About A Colu
2f5d0 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a mn Of A Table.**
2f5e0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
2f5f0 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 e returns metada
2f600 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 ta about a speci
2f610 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 fic column of a
2f620 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 specific.** data
2f630 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 base table acces
2f640 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 sible using the
2f650 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2f660 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 tion] handle.**
2f670 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
2f680 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 rst function arg
2f690 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ument..**.** ^Th
2f6a0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e e column is iden
2f6b0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 tified by the se
2f6c0 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 cond, third and
2f6d0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2f6e0 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e s to.** this fun
2f6f0 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f ction. ^The seco
2f700 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
2f710 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 either the name
2f720 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
2f730 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c ** (i.e. "main",
2f740 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 "temp", or an a
2f750 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
2f760 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 ) containing the
2f770 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 specified.** ta
2f780 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 ble or NULL. ^If
2f790 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 it is NULL, the
2f7a0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 n all attached d
2f7b0 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 atabases are sea
2f7c0 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 rched.** for the
2f7d0 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 table using the
2f7e0 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 same algorithm
2f7f0 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 used by the data
2f800 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a base engine to.*
2f810 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c * resolve unqual
2f820 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 ified table refe
2f830 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 rences..**.** ^T
2f840 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 he third and fou
2f850 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 rth parameters t
2f860 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 o this function
2f870 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e are the table an
2f880 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 d column.** name
2f890 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 of the desired
2f8a0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 column, respecti
2f8b0 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 vely. Neither of
2f8c0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 these parameter
2f8d0 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c s.** may be NULL
2f8e0 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 ..**.** ^Metadat
2f8f0 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 a is returned by
2f900 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 writing to the
2f910 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 memory locations
2f920 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 passed as the 5
2f930 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 th.** and subseq
2f940 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 uent parameters
2f950 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
2f960 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 . ^Any of these
2f970 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 arguments may be
2f980 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 .** NULL, in whi
2f990 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 ch case the corr
2f9a0 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e esponding elemen
2f9b0 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 t of metadata is
2f9c0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 omitted..**.**
2f9d0 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ^(<blockquote>.*
2f9e0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
2f9f0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
2fa00 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 Parameter <th>
2fa10 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c Output<br>Type <
2fa20 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e th> Description
2fa30 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 .**.** <tr><td>
2fa40 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 5th <td> const c
2fa50 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 har* <td> Data t
2fa60 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ype.** <tr><td>
2fa70 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 6th <td> const c
2fa80 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f har* <td> Name o
2fa90 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 f default collat
2faa0 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 ion sequence.**
2fab0 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 <tr><td> 7th <td
2fac0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 > int <t
2fad0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d d> True if colum
2fae0 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c n has a NOT NULL
2faf0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c constraint.** <
2fb00 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e tr><td> 8th <td>
2fb10 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
2fb20 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
2fb30 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 is part of the
2fb40 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c PRIMARY KEY.** <
2fb50 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e tr><td> 9th <td>
2fb60 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
2fb70 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
2fb80 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 is [AUTOINCREME
2fb90 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a NT].** </table>.
2fba0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e ** </blockquote>
2fbb0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 )^.**.** ^The me
2fbc0 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 mory pointed to
2fbd0 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 by the character
2fbe0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
2fbf0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 ed for the.** de
2fc00 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 claration type a
2fc10 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 nd collation seq
2fc20 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f uence is valid o
2fc30 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 nly until the ne
2fc40 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e xt.** call to an
2fc50 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e y SQLite API fun
2fc60 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 ction..**.** ^If
2fc70 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 the specified t
2fc80 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 able is actually
2fc90 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 a view, an [err
2fca0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
2fcb0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 rned..**.** ^If
2fcc0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f the specified co
2fcd0 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c lumn is "rowid",
2fce0 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 "oid" or "_rowi
2fcf0 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 d_" and an.** [I
2fd00 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
2fd10 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 EY] column has b
2fd20 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 een explicitly d
2fd30 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 eclared, then th
2fd40 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 e output.** para
2fd50 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 meters are set f
2fd60 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c or the explicitl
2fd70 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d y declared colum
2fd80 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 n. ^(If there is
2fd90 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c no.** explicitl
2fda0 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 y declared [INTE
2fdb0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d GER PRIMARY KEY]
2fdc0 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 column, then th
2fdd0 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 e output.** para
2fde0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 meters are set a
2fdf0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
2fe00 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 <pre>.** da
2fe10 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 ta type: "INTEGE
2fe20 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 R".** collat
2fe30 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 ion sequence: "B
2fe40 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f INARY".** no
2fe50 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 t null: 0.**
2fe60 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a primary key: 1.
2fe70 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 ** auto incr
2fe80 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 ement: 0.** </pr
2fe90 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 e>)^.**.** ^(Thi
2fea0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c s function may l
2feb0 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 oad one or more
2fec0 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 schemas from dat
2fed0 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 abase files. If
2fee0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 an.** error occu
2fef0 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 rs during this p
2ff00 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 rocess, or if th
2ff10 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c e requested tabl
2ff20 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 e or column.** c
2ff30 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 annot be found,
2ff40 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
2ff50 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
2ff60 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
2ff70 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 left.** in the
2ff80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2ff90 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 tion] (to be ret
2ffa0 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c rieved using sql
2ffb0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 ite3_errmsg()).)
2ffc0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 ^.**.** ^This AP
2ffd0 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 I is only availa
2ffe0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 ble if the libra
2fff0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 ry was compiled
30000 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
30010 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d ITE_ENABLE_COLUM
30020 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 N_METADATA] C-pr
30030 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f eprocessor symbo
30040 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e l defined..*/.in
30050 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f t sqlite3_table_
30060 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 column_metadata(
30070 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
30080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
30090 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e * Connection han
300a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
300b0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 har *zDbName,
300c0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
300d0 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f name or NULL */
300e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
300f0 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f TableName, /
30100 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a * Table name */.
30110 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 const char *zC
30120 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a olumnName, /*
30130 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a Column name */.
30140 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 char const **p
30150 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a zDataType, /*
30160 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 OUTPUT: Declare
30170 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 d data type */.
30180 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a char const **pz
30190 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 CollSeq, /*
301a0 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f OUTPUT: Collatio
301b0 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 n sequence name
301c0 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 */. int *pNotNu
301d0 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ll,
301e0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 /* OUTPUT: True
301f0 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e if NOT NULL con
30200 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a straint exists *
30210 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 /. int *pPrimar
30220 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 yKey,
30230 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 /* OUTPUT: True
30240 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f if column part o
30250 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 f PK */. int *p
30260 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 Autoinc
30270 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
30280 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
30290 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e is auto-incremen
302a0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t */.);../*.** C
302b0 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e API3REF: Load An
302c0 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a Extension.**.**
302d0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 ^This interface
302e0 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 loads an SQLite
302f0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 extension libra
30300 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 ry from the name
30310 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 d file..**.** ^T
30320 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f he sqlite3_load_
30330 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 extension() inte
30340 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
30350 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c o load an.** SQL
30360 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 ite extension li
30370 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 brary contained
30380 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c in the file zFil
30390 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e e..**.** ^The en
303a0 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 try point is zPr
303b0 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 oc..** ^zProc ma
303c0 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 y be 0, in which
303d0 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f case the name o
303e0 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e f the entry poin
303f0 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f t.** defaults to
30400 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 "sqlite3_extens
30410 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 ion_init"..** ^T
30420 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f he sqlite3_load_
30430 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 extension() inte
30440 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a rface returns.**
30450 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
30460 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c success and [SQL
30470 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f ITE_ERROR] if so
30480 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f mething goes wro
30490 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 ng..** ^If an er
304a0 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 ror occurs and p
304b0 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 zErrMsg is not 0
304c0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 , then the.** [s
304d0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
304e0 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 nsion()] interfa
304f0 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 ce shall attempt
30500 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 to.** fill *pzE
30510 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 rrMsg with error
30520 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 message text st
30530 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a ored in memory.*
30540 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 * obtained from
30550 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
30560 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 )]. The calling
30570 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 function.** shou
30580 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d ld free this mem
30590 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b ory by calling [
305a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
305b0 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f .**.** ^Extensio
305c0 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 n loading must b
305d0 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a e enabled using.
305e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 ** [sqlite3_enab
305f0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
30600 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 n()] prior to ca
30610 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a lling this API,.
30620 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 ** otherwise an
30630 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
30640 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 turned..**.** Se
30650 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 e also the [load
30660 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c _extension() SQL
30670 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 function]..*/.i
30680 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f nt sqlite3_load_
30690 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c extension(. sql
306a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
306b0 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 /* Load the e
306c0 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 xtension into th
306d0 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e is database conn
306e0 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 ection */. cons
306f0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 t char *zFile,
30700 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
30710 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 shared library
30720 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e containing exten
30730 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 sion */. const
30740 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 char *zProc,
30750 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 /* Entry point.
30760 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 Derived from zF
30770 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 ile if 0 */. ch
30780 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 ar **pzErrMsg
30790 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 /* Put error
307a0 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 message here if
307b0 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a not 0 */.);../*
307c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
307d0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
307e0 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e Extension Loadin
307f0 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e g.**.** ^So as n
30800 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 ot to open secur
30810 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 ity holes in old
30820 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 er applications
30830 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 that are.** unpr
30840 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 epared to deal w
30850 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f ith extension lo
30860 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 ading, and as a
30870 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 means of disabli
30880 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 ng.** extension
30890 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 loading while ev
308a0 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e aluating user-en
308b0 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 tered SQL, the f
308c0 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 ollowing API.**
308d0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 is provided to t
308e0 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 urn the [sqlite3
308f0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
30900 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 )] mechanism on
30910 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e and off..**.** ^
30920 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e Extension loadin
30930 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 g is off by defa
30940 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 ult. See ticket
30950 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 #1863..** ^Call
30960 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 the sqlite3_enab
30970 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
30980 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 n() routine with
30990 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 onoff==1.** to
309a0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c turn extension l
309b0 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 oading on and ca
309c0 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 ll it with onoff
309d0 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 ==0 to turn.** i
309e0 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e t back off again
309f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
30a00 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 _enable_load_ext
30a10 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a ension(sqlite3 *
30a20 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a db, int onoff);.
30a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
30a40 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c Automatically L
30a50 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e oad An Extension
30a60 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 s.**.** ^This AP
30a70 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 I can be invoked
30a80 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 at program star
30a90 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 tup in order to
30aa0 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 register.** one
30ab0 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c or more statical
30ac0 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 ly linked extens
30ad0 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 ions that will b
30ae0 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 e available.** t
30af0 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 o all new [datab
30b00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
30b10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 ..**.** ^(This r
30b20 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 outine stores a
30b30 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 pointer to the e
30b40 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 xtension entry p
30b50 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 oint.** in an ar
30b60 72 61 79 20 74 68 61 74 20 69 73 20 6f 62 74 61 ray that is obta
30b70 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
30b80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 e3_malloc()]. T
30b90 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 hat memory.** is
30ba0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 deallocated by
30bb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 [sqlite3_reset_a
30bc0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d uto_extension()]
30bd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 .)^.**.** ^This
30be0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
30bf0 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 rs an extension
30c00 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 entry point that
30c10 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 is.** automatic
30c20 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 65 ally invoked whe
30c30 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61 74 never a new [dat
30c40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
30c50 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65 64 20 75 ].** is opened u
30c60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 sing [sqlite3_op
30c70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
30c80 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72 open16()],.** or
30c90 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
30ca0 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70 6c 69 63 2()]..** ^Duplic
30cb0 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 ate extensions a
30cc0 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 re detected so c
30cd0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 alling this rout
30ce0 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 ine.** multiple
30cf0 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 times with the s
30d00 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 ame extension is
30d10 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 20 5e 41 harmless..** ^A
30d20 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
30d30 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 ons apply across
30d40 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f all threads..*/
30d50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 .int sqlite3_aut
30d60 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 o_extension(void
30d70 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 (*xEntryPoint)(
30d80 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void));../*.** C
30d90 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
30da0 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 utomatic Extensi
30db0 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a on Loading.**.**
30dc0 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ^(This function
30dd0 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 disables all pr
30de0 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 eviously registe
30df0 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a red automatic.**
30e00 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 49 74 20 extensions. It
30e10 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
30e20 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a t of all prior.*
30e30 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f * [sqlite3_auto_
30e40 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c extension()] cal
30e50 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 ls.)^.**.** ^Thi
30e60 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 s function disab
30e70 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65 78 les automatic ex
30e80 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 tensions in all
30e90 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 threads..*/.void
30ea0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 sqlite3_reset_a
30eb0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f uto_extension(vo
30ec0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 id);../*.** The
30ed0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 interface to the
30ee0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d virtual-table m
30ef0 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 echanism is curr
30f00 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 ently considered
30f10 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 .** to be experi
30f20 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 mental. The int
30f30 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 erface might cha
30f40 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 nge in incompati
30f50 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 ble ways..** If
30f60 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 this is a proble
30f70 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f m for you, do no
30f80 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 t use the interf
30f90 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 ace at this time
30fa0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
30fb0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d virtual-table m
30fc0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 echanism stabili
30fd0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 zes, we will dec
30fe0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 lare the.** inte
30ff0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 rface fixed, sup
31000 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 port it indefini
31010 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 tely, and remove
31020 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a this comment..*
31030 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 /../*.** Structu
31040 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 res used by the
31050 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e virtual table in
31060 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 terface.*/.typed
31070 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
31080 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 3_vtab sqlite3_v
31090 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 tab;.typedef str
310a0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
310b0 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 x_info sqlite3_i
310c0 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 ndex_info;.typed
310d0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
310e0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 3_vtab_cursor sq
310f0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
31100 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 r;.typedef struc
31110 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 t sqlite3_module
31120 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b sqlite3_module;
31130 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31140 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 : Virtual Table
31150 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 Object.** KEYWOR
31160 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 DS: sqlite3_modu
31170 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c le {virtual tabl
31180 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 e module}.**.**
31190 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 This structure,
311a0 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 sometimes called
311b0 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 a a "virtual ta
311c0 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a ble module", .**
311d0 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 defines the imp
311e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 lementation of a
311f0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 [virtual tables
31200 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 ]. .** This str
31210 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 ucture consists
31220 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 mostly of method
31230 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 s for the module
31240 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 ..**.** ^A virtu
31250 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 al table module
31260 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 is created by fi
31270 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 lling in a persi
31280 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 stent.** instanc
31290 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 e of this struct
312a0 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 ure and passing
312b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 a pointer to tha
312c0 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f t instance.** to
312d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
312e0 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 _module()] or [s
312f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
31300 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e dule_v2()]..** ^
31310 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e The registration
31320 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 remains valid u
31330 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 ntil it is repla
31340 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 ced by a differe
31350 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 nt.** module or
31360 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 until the [datab
31370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
31380 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e closes. The con
31390 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 tent.** of this
313a0 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e structure must n
313b0 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 ot change while
313c0 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 it is registered
313d0 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 with.** any dat
313e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
313f0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 ..*/.struct sqli
31400 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 te3_module {. i
31410 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
31420 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 nt (*xCreate)(sq
31430 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 lite3*, void *pA
31440 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 ux,.
31450 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e int argc, con
31460 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 st char *const*a
31470 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 rgv,.
31480 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 sqlite3_vtab
31490 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a **ppVTab, char*
314a0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e *);. int (*xCon
314b0 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 nect)(sqlite3*,
314c0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 void *pAux,.
314d0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 int a
314e0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 rgc, const char
314f0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 *const*argv,.
31500 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 sqli
31510 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 te3_vtab **ppVTa
31520 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e b, char**);. in
31530 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 t (*xBestIndex)(
31540 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
31550 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 Tab, sqlite3_ind
31560 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 ex_info*);. int
31570 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 (*xDisconnect)(
31580 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
31590 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 Tab);. int (*xD
315a0 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f estroy)(sqlite3_
315b0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
315c0 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c int (*xOpen)(sql
315d0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
315e0 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 , sqlite3_vtab_c
315f0 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 ursor **ppCursor
31600 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 );. int (*xClos
31610 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f e)(sqlite3_vtab_
31620 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 cursor*);. int
31630 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 (*xFilter)(sqlit
31640 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
31650 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e int idxNum, con
31660 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c st char *idxStr,
31670 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
31680 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 int argc, sqlit
31690 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 e3_value **argv)
316a0 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 ;. int (*xNext)
316b0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 (sqlite3_vtab_cu
316c0 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a rsor*);. int (*
316d0 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 xEof)(sqlite3_vt
316e0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 ab_cursor*);. i
316f0 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 nt (*xColumn)(sq
31700 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
31710 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 r*, sqlite3_cont
31720 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ext*, int);. in
31730 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 t (*xRowid)(sqli
31740 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a te3_vtab_cursor*
31750 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
31760 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 *pRowid);. int
31770 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 (*xUpdate)(sqlit
31780 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 e3_vtab *, int,
31790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a sqlite3_value **
317a0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
317b0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 *);. int (*xBeg
317c0 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 in)(sqlite3_vtab
317d0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 *pVTab);. int
317e0 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 (*xSync)(sqlite3
317f0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
31800 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 int (*xCommit)(
31810 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
31820 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 Tab);. int (*xR
31830 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 ollback)(sqlite3
31840 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
31850 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 int (*xFindFunc
31860 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 tion)(sqlite3_vt
31870 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e ab *pVtab, int n
31880 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 Arg, const char
31890 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 *zName,.
318a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
318b0 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 oid (**pxFunc)(s
318c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
318d0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
318e0 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 e**),.
318f0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 voi
31900 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e d **ppArg);. in
31910 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c t (*xRename)(sql
31920 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
31930 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
31940 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ew);.};../*.** C
31950 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c API3REF: Virtual
31960 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 Table Indexing
31970 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b Information.** K
31980 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 EYWORDS: sqlite3
31990 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a _index_info.**.*
319a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
319b0 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 dex_info structu
319c0 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 re and its subst
319d0 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 ructures is used
319e0 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f to.** pass info
319f0 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 rmation into and
31a00 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 receive the rep
31a10 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 ly from the [xBe
31a20 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 stIndex].** meth
31a30 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c od of a [virtual
31a40 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 table module].
31a50 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 The fields unde
31a60 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 r **Inputs** are
31a70 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 the.** inputs t
31a80 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 o xBestIndex and
31a90 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 are read-only.
31aa0 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 xBestIndex inse
31ab0 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c rts its.** resul
31ac0 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 ts into the **Ou
31ad0 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a tputs** fields..
31ae0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e **.** ^(The aCon
31af0 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 straint[] array
31b00 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c records WHERE cl
31b10 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 ause constraints
31b20 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a of the form:.**
31b30 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 .** <pre>column
31b40 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a OP expr</pre>.**
31b50 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 .** where OP is
31b60 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 =, <, <=,
31b70 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 >, or >=.)
31b80 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 ^ ^(The particu
31b90 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a lar operator is.
31ba0 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f ** stored in aCo
31bb0 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 29 5e nstraint[].op.)^
31bc0 20 20 5e 28 54 68 65 20 69 6e 64 65 78 20 6f 66 ^(The index of
31bd0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 the column is s
31be0 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e tored in.** aCon
31bf0 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d straint[].iColum
31c00 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61 n.)^ ^(aConstra
31c10 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 int[].usable is
31c20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 TRUE if the.** e
31c30 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 xpr on the right
31c40 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 -hand side can b
31c50 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 e evaluated (and
31c60 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 thus the constr
31c70 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c aint.** is usabl
31c80 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 e) and false if
31c90 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a it cannot.)^.**.
31ca0 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65 ** ^The optimize
31cb0 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 r automatically
31cc0 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 inverts terms of
31cd0 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 the form "expr
31ce0 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e OP column".** an
31cf0 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 d makes other si
31d00 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f mplifications to
31d10 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 the WHERE claus
31d20 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 e in an attempt
31d30 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e to.** get as man
31d40 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 y WHERE clause t
31d50 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f erms into the fo
31d60 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 rm shown above a
31d70 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e s possible..** ^
31d80 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b The aConstraint[
31d90 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 ] array only rep
31da0 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 orts WHERE claus
31db0 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 72 65 e terms that are
31dc0 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f 20 .** relevant to
31dd0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 the particular v
31de0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 irtual table bei
31df0 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a ng queried..**.*
31e00 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 * ^Information a
31e10 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 bout the ORDER B
31e20 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 Y clause is stor
31e30 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d ed in aOrderBy[]
31e40 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 ..** ^Each term
31e50 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f of aOrderBy reco
31e60 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 rds a column of
31e70 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
31e80 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b use..**.** The [
31e90 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 xBestIndex] meth
31ea0 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f od must fill aCo
31eb0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 nstraintUsage[]
31ec0 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e with information
31ed0 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 .** about what p
31ee0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 arameters to pas
31ef0 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e s to xFilter. ^
31f00 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 If argvIndex>0 t
31f10 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 hen.** the right
31f20 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 -hand side of th
31f30 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
31f40 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 aConstraint[] is
31f50 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e evaluated.** an
31f60 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 d becomes the ar
31f70 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 gvIndex-th entry
31f80 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20 in argv. ^(If
31f90 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
31fa0 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 [].omit.** is tr
31fb0 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e ue, then the con
31fc0 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d straint is assum
31fd0 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 ed to be fully h
31fe0 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a andled by the.**
31ff0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 virtual table a
32000 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 nd is not checke
32010 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 d again by SQLit
32020 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e.)^.**.** ^The
32030 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 idxNum and idxPt
32040 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 r values are rec
32050 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 orded and passed
32060 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 into the.** [xF
32070 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a ilter] method..*
32080 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 * ^[sqlite3_free
32090 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66 ()] is used to f
320a0 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 6e ree idxPtr if an
320b0 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 d only if.** nee
320c0 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 dToFreeIdxPtr is
320d0 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 true..**.** ^Th
320e0 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 e orderByConsume
320f0 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 d means that out
32100 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65 put from [xFilte
32110 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20 r]/[xNext] will
32120 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 occur in.** the
32130 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f correct order to
32140 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44 satisfy the ORD
32150 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 ER BY clause so
32160 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65 that no separate
32170 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70 .** sorting step
32180 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a is required..**
32190 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74 .** ^The estimat
321a0 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 edCost value is
321b0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 an estimate of t
321c0 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 he cost of doing
321d0 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c the.** particul
321e0 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 ar lookup. A fu
321f0 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 ll scan of a tab
32200 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 le with N entrie
32210 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a s should have.**
32220 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 a cost of N. A
32230 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f binary search o
32240 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 f a table of N e
32250 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 ntries should ha
32260 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 ve a.** cost of
32270 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f approximately lo
32280 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 g(N)..*/.struct
32290 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
322a0 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 fo {. /* Inputs
322b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 */. int nConst
322c0 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 raint;
322d0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e /* Number of en
322e0 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 tries in aConstr
322f0 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 aint */. struct
32300 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 sqlite3_index_c
32310 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 onstraint {.
32320 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 int iColumn;
32330 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
32340 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e lumn on left-han
32350 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 d side of constr
32360 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 aint */. uns
32370 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 igned char op;
32380 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 /* Constr
32390 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f aint operator */
323a0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
323b0 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 har usable;
323c0 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 /* True if this
323d0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 constraint is us
323e0 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 able */. int
323f0 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 iTermOffset;
32400 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 /* Used i
32410 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 nternally - xBes
32420 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 tIndex should ig
32430 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f nore */. } *aCo
32440 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 nstraint;
32450 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 /* Table of
32460 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f WHERE clause co
32470 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 nstraints */. i
32480 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 nt nOrderBy;
32490 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
324a0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
324b0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
324c0 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 use */. struct
324d0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 sqlite3_index_or
324e0 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 derby {. int
324f0 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 iColumn;
32500 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e /* Column
32510 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 number */.
32520 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 unsigned char de
32530 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 sc; /* Tru
32540 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c e for DESC. Fal
32550 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 se for ASC. */.
32560 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 } *aOrderBy;
32570 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 /* T
32580 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
32590 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 se */. /* Outpu
325a0 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 ts */. struct s
325b0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e qlite3_index_con
325c0 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a straint_usage {.
325d0 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 int argvInde
325e0 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 x; /*
325f0 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e if >0, constrain
32600 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 t is part of arg
32610 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a v to xFilter */.
32620 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 unsigned cha
32630 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 r omit; /*
32640 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 Do not code a te
32650 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 st for this cons
32660 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 traint */. } *a
32670 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b ConstraintUsage;
32680 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 . int idxNum;
32690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
326a0 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 Number used to
326b0 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 identify the ind
326c0 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 ex */. char *id
326d0 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 xStr;
326e0 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f /* String, po
326f0 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 ssibly obtained
32700 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c from sqlite3_mal
32710 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 loc */. int nee
32720 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 dToFreeIdxStr;
32730 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 /* Free idxS
32740 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 tr using sqlite3
32750 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 _free() if true
32760 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 */. int orderBy
32770 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 Consumed;
32780 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 /* True if outpu
32790 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 t is already ord
327a0 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 ered */. double
327b0 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 estimatedCost;
327c0 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 /* Estimate
327d0 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 d cost of using
327e0 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b this index */.};
327f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
32800 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
32810 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 _EQ 2.#define
32820 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
32830 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 NSTRAINT_GT 4
32840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
32850 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
32860 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 _LE 8.#define
32870 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
32880 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 NSTRAINT_LT 1
32890 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
328a0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
328b0 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 T_GE 32.#defi
328c0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
328d0 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 CONSTRAINT_MATCH
328e0 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 64../*.** CAPI3
328f0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
32900 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d Virtual Table Im
32910 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a plementation.**.
32920 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
32930 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 72 es are used to r
32940 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 egister a new [v
32950 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
32960 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d ule] name..** ^M
32970 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 odule names must
32980 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62 be registered b
32990 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e efore.** creatin
329a0 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c g a new [virtual
329b0 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 table] using th
329c0 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65 66 e module and bef
329d0 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 ore using a.** p
329e0 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74 reexisting [virt
329f0 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 ual table] for t
32a00 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a he module..**.**
32a10 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d ^The module nam
32a20 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 e is registered
32a30 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 on the [database
32a40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 connection] spe
32a50 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 cified.** by the
32a60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
32a70 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 . ^The name of
32a80 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 the module is gi
32a90 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 ven by the .** s
32aa0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
32ab0 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 ^The third par
32ac0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
32ad0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d ter to.** the im
32ae0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
32af0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 the [virtual tab
32b00 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 le module]. ^T
32b10 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 he fourth.** par
32b20 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 ameter is an arb
32b30 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61 itrary client da
32b40 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 ta pointer that
32b50 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 is passed throug
32b60 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 h.** into the [x
32b70 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f Create] and [xCo
32b80 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f nnect] methods o
32b90 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 f the virtual ta
32ba0 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 ble module.** wh
32bb0 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c en a new virtual
32bc0 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65 69 table is be bei
32bd0 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72 65 ng created or re
32be0 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a initialized..**.
32bf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
32c00 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 create_module_v2
32c10 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 () interface has
32c20 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 a fifth paramet
32c30 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 er which.** is a
32c40 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 pointer to a de
32c50 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 structor for the
32c60 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e pClientData. ^
32c70 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 SQLite will.** i
32c80 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 nvoke the destru
32c90 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 ctor function (i
32ca0 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c f it is not NULL
32cb0 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a ) when SQLite.**
32cc0 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 no longer needs
32cd0 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 the pClientData
32ce0 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 pointer. ^The
32cf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
32d00 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72 odule().** inter
32d10 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 face is equivale
32d20 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 nt to sqlite3_cr
32d30 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 eate_module_v2()
32d40 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 with a NULL.**
32d50 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69 destructor..*/.i
32d60 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
32d70 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 e_module(. sqli
32d80 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
32d90 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 /* SQLite
32da0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 connection to r
32db0 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 egister module w
32dc0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ith */. const c
32dd0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 har *zName,
32de0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
32df0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 he module */. c
32e00 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 onst sqlite3_mod
32e10 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 ule *p, /* Met
32e20 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 hods for the mod
32e30 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 ule */. void *p
32e40 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 ClientData
32e50 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 /* Client da
32e60 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 ta for xCreate/x
32e70 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e Connect */.);.in
32e80 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
32e90 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 _module_v2(. sq
32ea0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
32eb0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 /* SQLi
32ec0 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f te connection to
32ed0 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 register module
32ee0 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 with */. const
32ef0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 char *zName,
32f00 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
32f10 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 the module */.
32f20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d const sqlite3_m
32f30 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d odule *p, /* M
32f40 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d ethods for the m
32f50 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 odule */. void
32f60 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 *pClientData,
32f70 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 /* Client
32f80 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 data for xCreate
32f90 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 /xConnect */. v
32fa0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 oid(*xDestroy)(v
32fb0 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 oid*) /* Mod
32fc0 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 ule destructor f
32fd0 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f unction */.);../
32fe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 *.** CAPI3REF: V
32ff0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 irtual Table Ins
33000 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 tance Object.**
33010 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
33020 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 3_vtab.**.** Eve
33030 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ry [virtual tabl
33040 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d e module] implem
33050 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 entation uses a
33060 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 subclass.** of t
33070 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 his object to de
33080 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 scribe a particu
33090 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 lar instance.**
330a0 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 of the [virtual
330b0 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 table]. Each su
330c0 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 bclass will.** b
330d0 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 e tailored to th
330e0 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
330f0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 of the module i
33100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a mplementation..*
33110 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 * The purpose of
33120 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 this superclass
33130 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 is to define ce
33140 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 rtain fields tha
33150 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 t are.** common
33160 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d to all module im
33170 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a plementations..*
33180 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 *.** ^Virtual ta
33190 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e bles methods can
331a0 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 set an error me
331b0 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 ssage by assigni
331c0 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f ng a.** string o
331d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
331e0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
331f0 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 to zErrMsg. Th
33200 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a e method should.
33210 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 ** take care tha
33220 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 t any prior stri
33230 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 ng is freed by a
33240 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
33250 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 3_free()].** pri
33260 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 or to assigning
33270 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 a new string to
33280 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 zErrMsg. ^After
33290 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
332a0 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 ge.** is deliver
332b0 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 ed up to the cli
332c0 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c ent application,
332d0 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c the string will
332e0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
332f0 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 y.** freed by sq
33300 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 lite3_free() and
33310 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 the zErrMsg fie
33320 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 ld will be zeroe
33330 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c d..*/.struct sql
33340 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f ite3_vtab {. co
33350 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 nst sqlite3_modu
33360 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a le *pModule; /*
33370 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 The module for
33380 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 this virtual tab
33390 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 le */. int nRef
333a0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
333b0 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f /* NO LO
333c0 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 NGER USED */. c
333d0 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 har *zErrMsg;
333e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
333f0 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 * Error message
33400 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 from sqlite3_mpr
33410 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 intf() */. /* V
33420 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 irtual table imp
33430 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c lementations wil
33440 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 l typically add
33450 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 additional field
33460 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 s */.};../*.** C
33470 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c API3REF: Virtual
33480 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 Table Cursor Ob
33490 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ject.** KEYWORDS
334a0 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 : sqlite3_vtab_c
334b0 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 ursor {virtual t
334c0 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a able cursor}.**.
334d0 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 ** Every [virtua
334e0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 l table module]
334f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 implementation u
33500 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f ses a subclass o
33510 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 f the.** followi
33520 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 ng structure to
33530 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 describe cursors
33540 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f that point into
33550 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c the.** [virtual
33560 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 table] and are
33570 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 used.** to loop
33580 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 through the virt
33590 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 ual table. Curs
335a0 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20 ors are created
335b0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
335c0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 lite3_module.xOp
335d0 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 en | xOpen] meth
335e0 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 od of the module
335f0 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79 and are destroy
33600 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 ed.** by the [sq
33610 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c lite3_module.xCl
33620 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 ose | xClose] me
33630 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61 thod. Cursors a
33640 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 re used.** by th
33650 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e e [xFilter], [xN
33660 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 ext], [xEof], [x
33670 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 Column], and [xR
33680 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a owid] methods.**
33690 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 of the module.
336a0 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 Each module imp
336b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c lementation will
336c0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 define.** the c
336d0 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 ontent of a curs
336e0 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 or structure to
336f0 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 suit its own nee
33700 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 ds..**.** This s
33710 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 uperclass exists
33720 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 in order to def
33730 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 ine fields of th
33740 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a e cursor that.**
33750 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 are common to a
33760 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ll implementatio
33770 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 ns..*/.struct sq
33780 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
33790 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 r {. sqlite3_vt
337a0 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 ab *pVtab;
337b0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 /* Virtual table
337c0 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 of this cursor
337d0 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 */. /* Virtual
337e0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 table implementa
337f0 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 tions will typic
33800 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f ally add additio
33810 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b nal fields */.};
33820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
33830 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 : Declare The Sc
33840 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 hema Of A Virtua
33850 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 l Table.**.** ^T
33860 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 he [xCreate] and
33870 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 [xConnect] meth
33880 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 ods of a.** [vir
33890 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
338a0 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 e] call this int
338b0 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 erface.** to dec
338c0 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 lare the format
338d0 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 (the names and d
338e0 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 atatypes of the
338f0 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 columns) of.** t
33900 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 he virtual table
33910 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 s they implement
33920 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
33930 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 _declare_vtab(sq
33940 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 lite3*, const ch
33950 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a ar *zSQL);../*.*
33960 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 * CAPI3REF: Over
33970 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 load A Function
33980 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 For A Virtual Ta
33990 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 ble.**.** ^(Virt
339a0 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 ual tables can p
339b0 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 rovide alternati
339c0 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ve implementatio
339d0 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ns of functions.
339e0 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46 ** using the [xF
339f0 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 indFunction] met
33a00 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74 hod of the [virt
33a10 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 ual table module
33a20 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 ]. .** But glob
33a30 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 al versions of t
33a40 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a hose functions.*
33a50 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 * must exist in
33a60 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 order to be over
33a70 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 loaded.)^.**.**
33a80 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 ^(This API makes
33a90 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 sure a global v
33aa0 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 ersion of a func
33ab0 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 tion with a part
33ac0 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 icular.** name a
33ad0 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 nd number of par
33ae0 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 ameters exists.
33af0 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 If no such func
33b00 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 tion exists.** b
33b10 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 efore this API i
33b20 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 s called, a new
33b30 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 function is crea
33b40 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70 ted.)^ ^The imp
33b50 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f lementation.** o
33b60 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 f the new functi
33b70 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 on always causes
33b80 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f an exception to
33b90 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a be thrown. So.
33ba0 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 ** the new funct
33bb0 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 ion is not good
33bc0 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 for anything by
33bd0 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c itself. Its onl
33be0 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 y.** purpose is
33bf0 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c to be a placehol
33c00 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 der function tha
33c10 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 t can be overloa
33c20 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 ded.** by a [vir
33c30 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a tual table]..*/.
33c40 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 int sqlite3_over
33c50 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 load_function(sq
33c60 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 lite3*, const ch
33c70 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 ar *zFuncName, i
33c80 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a nt nArg);../*.**
33c90 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 The interface t
33ca0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 o the virtual-ta
33cb0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 ble mechanism de
33cc0 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 fined above (bac
33cd0 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d k up.** to a com
33ce0 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 ment remarkably
33cf0 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 similar to this
33d00 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c one) is currentl
33d10 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 y considered.**
33d20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 to be experiment
33d30 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 al. The interfa
33d40 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 ce might change
33d50 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 in incompatible
33d60 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 ways..** If this
33d70 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f is a problem fo
33d80 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 r you, do not us
33d90 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 e the interface
33da0 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a at this time..**
33db0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 .** When the vir
33dc0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 tual-table mecha
33dd0 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c nism stabilizes,
33de0 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 we will declare
33df0 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 the.** interfac
33e00 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 e fixed, support
33e10 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 it indefinitely
33e20 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 , and remove thi
33e30 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f s comment..*/../
33e40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
33e50 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 Handle To An Op
33e60 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f en BLOB.** KEYWO
33e70 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c RDS: {BLOB handl
33e80 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 e} {BLOB handles
33e90 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 }.**.** An insta
33ea0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
33eb0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e ct represents an
33ec0 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 open BLOB on wh
33ed0 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ich.** [sqlite3_
33ee0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 blob_open | incr
33ef0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f emental BLOB I/O
33f00 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d ] can be perform
33f10 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 ed..** ^Objects
33f20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72 65 of this type are
33f30 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c created by [sql
33f40 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 ite3_blob_open()
33f50 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 ].** and destroy
33f60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 ed by [sqlite3_b
33f70 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a lob_close()]..**
33f80 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 ^The [sqlite3_b
33f90 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 lob_read()] and
33fa0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 [sqlite3_blob_wr
33fb0 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ite()] interface
33fc0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 s.** can be used
33fd0 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 to read or writ
33fe0 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 e small subsecti
33ff0 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e ons of the BLOB.
34000 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
34010 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 3_blob_bytes()]
34020 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
34030 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
34040 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e e BLOB in bytes.
34050 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
34060 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 ct sqlite3_blob
34070 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f sqlite3_blob;../
34080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
34090 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 pen A BLOB For I
340a0 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a ncremental I/O.*
340b0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 *.** ^(This inte
340c0 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b rfaces opens a [
340d0 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 BLOB handle | ha
340e0 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f ndle] to the BLO
340f0 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 B located.** in
34100 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e row iRow, column
34110 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 zColumn, table
34120 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 zTable in databa
34130 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 se zDb;.** in ot
34140 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 her words, the s
34150 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f ame BLOB that wo
34160 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 uld be selected
34170 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a by:.**.** <pre>.
34180 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 ** SELECT zC
34190 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a olumn FROM zDb.z
341a0 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 Table WHERE [row
341b0 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c id] = iRow;.** <
341c0 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 /pre>)^.**.** ^I
341d0 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 f the flags para
341e0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 meter is non-zer
341f0 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 o, then the BLOB
34200 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
34210 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 ead.** and write
34220 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74 20 access. ^If it
34230 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f is zero, the BLO
34240 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 B is opened for
34250 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 read access..**
34260 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 ^It is not possi
34270 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f ble to open a co
34280 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 lumn that is par
34290 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 t of an index or
342a0 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 primary .** key
342b0 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 for writing. ^I
342c0 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 f [foreign key c
342d0 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20 onstraints] are
342e0 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a enabled, it is .
342f0 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 ** not possible
34300 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e to open a column
34310 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 that is part of
34320 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 a [child key] f
34330 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a or writing..**.*
34340 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 * ^Note that the
34350 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 database name i
34360 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 s not the filena
34370 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 me that contains
34380 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
34390 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20 but rather the
343a0 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 symbolic name of
343b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 the database th
343c0 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61 66 at.** appears af
343d0 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f ter the AS keywo
343e0 72 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 rd when the data
343f0 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 base is connecte
34400 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d d using [ATTACH]
34410 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61 ..** ^For the ma
34420 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 in database file
34430 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e , the database n
34440 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a ame is "main"..*
34450 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62 6c * ^For TEMP tabl
34460 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 es, the database
34470 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e name is "temp".
34480 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 .**.** ^(On succ
34490 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ess, [SQLITE_OK]
344a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
344b0 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 the new [BLOB h
344c0 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 andle] is writte
344d0 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e n.** to *ppBlob.
344e0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 Otherwise an [e
344f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
34500 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c turned and *ppBl
34510 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 ob is set.** to
34520 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 be a null pointe
34530 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75 r.)^.** ^This fu
34540 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 nction sets the
34550 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
34560 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 tion] error code
34570 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 and message.**
34580 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b accessible via [
34590 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
345a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
345b0 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 errmsg()] and re
345c0 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f lated.** functio
345d0 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 ns. ^Note that t
345e0 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 he *ppBlob varia
345f0 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e ble is always in
34600 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a itialized in a.*
34610 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 * way that makes
34620 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f it safe to invo
34630 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ke [sqlite3_blob
34640 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 _close()] on *pp
34650 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 Blob.** regardle
34660 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 ss of the succes
34670 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 s or failure of
34680 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a this routine..**
34690 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f 77 .** ^(If the row
346a0 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e that a BLOB han
346b0 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 dle points to is
346c0 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a modified by an.
346d0 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 ** [UPDATE], [DE
346e0 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e LETE], or by [ON
346f0 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d CONFLICT] side-
34700 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 effects.** then
34710 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 the BLOB handle
34720 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78 is marked as "ex
34730 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 pired"..** This
34740 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63 is true if any c
34750 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 olumn of the row
34760 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65 is changed, eve
34770 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 n a column.** ot
34780 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 her than the one
34790 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 the BLOB handle
347a0 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a is open on.)^.*
347b0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c * ^Calls to [sql
347c0 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 ite3_blob_read()
347d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 ] and [sqlite3_b
347e0 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 lob_write()] for
347f0 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c .** a expired BL
34800 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 OB handle fail w
34810 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f ith an return co
34820 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 de of [SQLITE_AB
34830 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 ORT]..** ^(Chang
34840 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 es written into
34850 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 a BLOB prior to
34860 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e the BLOB expirin
34870 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c g are not.** rol
34880 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 20 led back by the
34890 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 expiration of th
348a0 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 e BLOB. Such ch
348b0 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 anges will event
348c0 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 ually.** commit
348d0 69 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 if the transacti
348e0 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 on continues to
348f0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a completion.)^.**
34900 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b 73 71 .** ^Use the [sq
34910 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 lite3_blob_bytes
34920 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f ()] interface to
34930 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73 determine the s
34940 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 ize of.** the op
34950 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65 ened blob. ^The
34960 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 size of a blob
34970 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 may not be chang
34980 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e ed by this.** in
34990 74 65 72 66 61 63 65 2e 20 20 55 73 65 20 74 68 terface. Use th
349a0 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63 e [UPDATE] SQL c
349b0 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65 ommand to change
349c0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a the size of a.*
349d0 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 * blob..**.** ^T
349e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
349f0 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 _zeroblob()] and
34a00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
34a10 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 _zeroblob()] int
34a20 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 erfaces.** and t
34a30 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 he built-in [zer
34a40 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 oblob] SQL funct
34a50 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c ion can be used,
34a60 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 if desired,.**
34a70 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70 to create an emp
34a80 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 ty, zero-filled
34a90 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f blob in which to
34aa0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 75 read or write u
34ab0 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 sing.** this int
34ac0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f erface..**.** To
34ad0 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63 avoid a resourc
34ae0 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 e leak, every op
34af0 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d en [BLOB handle]
34b00 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c should eventual
34b10 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 ly.** be release
34b20 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b d by a call to [
34b30 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
34b40 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 se()]..*/.int sq
34b50 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 lite3_blob_open(
34b60 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 . sqlite3*,. c
34b70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a onst char *zDb,.
34b80 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 const char *zT
34b90 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 able,. const ch
34ba0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 ar *zColumn,. s
34bb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f qlite3_int64 iRo
34bc0 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a w,. int flags,.
34bd0 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a sqlite3_blob *
34be0 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a *ppBlob.);../*.*
34bf0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 * CAPI3REF: Clos
34c00 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a e A BLOB Handle.
34c10 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73 20 61 6e **.** ^Closes an
34c20 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 open [BLOB hand
34c30 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 le]..**.** ^Clos
34c40 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c ing a BLOB shall
34c50 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65 cause the curre
34c60 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 nt transaction t
34c70 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 o commit.** if t
34c80 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 here are no othe
34c90 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 r BLOBs, no pend
34ca0 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61 ing prepared sta
34cb0 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 tements, and the
34cc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
34cd0 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61 nection is in [a
34ce0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e utocommit mode].
34cf0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77 72 69 74 .** ^If any writ
34d00 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20 es were made to
34d10 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d the BLOB, they m
34d20 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20 ight be held in
34d30 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 cache.** until t
34d40 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 he close operati
34d50 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20 on if they will
34d60 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f fit..**.** ^(Clo
34d70 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 sing the BLOB of
34d80 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 ten forces the c
34d90 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f hanges.** out to
34da0 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 disk and so if
34db0 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f any I/O errors o
34dc0 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 ccur, they will
34dd0 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 likely occur.**
34de0 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e at the time when
34df0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f the BLOB is clo
34e00 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 sed. Any errors
34e10 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 that occur duri
34e20 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 ng.** closing ar
34e30 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 e reported as a
34e40 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 non-zero return
34e50 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e value.)^.**.** ^
34e60 28 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f (The BLOB is clo
34e70 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 sed unconditiona
34e80 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68 lly. Even if th
34e90 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
34ea0 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 ns.** an error c
34eb0 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 ode, the BLOB is
34ec0 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e still closed.)^
34ed0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 .**.** ^Calling
34ee0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 this routine wit
34ef0 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 h a null pointer
34f00 20 28 73 75 63 68 20 61 73 20 77 6f 75 6c 64 20 (such as would
34f10 62 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 be returned.** b
34f20 79 20 61 20 66 61 69 6c 65 64 20 63 61 6c 6c 20 y a failed call
34f30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 to [sqlite3_blob
34f40 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20 68 _open()]) is a h
34f50 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
34f60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c /.int sqlite3_bl
34f70 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 ob_close(sqlite3
34f80 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _blob *);../*.**
34f90 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 CAPI3REF: Retur
34fa0 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e n The Size Of An
34fb0 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a Open BLOB.**.**
34fc0 20 5e 52 65 74 75 72 6e 73 20 74 68 65 20 73 69 ^Returns the si
34fd0 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 ze in bytes of t
34fe0 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62 he BLOB accessib
34ff0 6c 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 le via the .** s
35000 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e uccessfully open
35010 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d ed [BLOB handle]
35020 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 in its only arg
35030 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a 20 ument. ^The.**
35040 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 incremental blob
35050 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63 61 I/O routines ca
35060 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f n only read or o
35070 76 65 72 77 72 69 74 69 6e 67 20 65 78 69 73 74 verwriting exist
35080 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 ing.** blob cont
35090 65 6e 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74 ent; they cannot
350a0 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 change the size
350b0 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a of a blob..**.*
350c0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f * This routine o
350d0 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b nly works on a [
350e0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 BLOB handle] whi
350f0 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 ch has been crea
35100 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f ted.** by a prio
35110 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c r successful cal
35120 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c l to [sqlite3_bl
35130 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 ob_open()] and w
35140 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 hich has not.**
35150 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b been closed by [
35160 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
35170 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 se()]. Passing
35180 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 any other pointe
35190 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 r in.** to this
351a0 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 routine results
351b0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 in undefined and
351c0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 probably undesi
351d0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a rable behavior..
351e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
351f0 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 lob_bytes(sqlite
35200 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 3_blob *);../*.*
35210 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 61 64 * CAPI3REF: Read
35220 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f Data From A BLO
35230 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a B Incrementally.
35240 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e **.** ^(This fun
35250 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f ction is used to
35260 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 read data from
35270 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 an open [BLOB ha
35280 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 ndle] into a.**
35290 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 caller-supplied
352a0 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 buffer. N bytes
352b0 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 of data are copi
352c0 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a ed into buffer Z
352d0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 .** from the ope
352e0 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 n BLOB, starting
352f0 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 at offset iOffs
35300 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 et.)^.**.** ^If
35310 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 offset iOffset i
35320 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 s less than N by
35330 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 tes from the end
35340 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a of the BLOB,.**
35350 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
35360 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
35370 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e no data is read.
35380 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f 66 66 73 ^If N or iOffs
35390 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 et is.** less th
353a0 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45 an zero, [SQLITE
353b0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 _ERROR] is retur
353c0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 ned and no data
353d0 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e 54 68 65 is read..** ^The
353e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f size of the blo
353f0 62 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65 b (and hence the
35400 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f maximum value o
35410 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 f N+iOffset).**
35420 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 can be determine
35430 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c d using the [sql
35440 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 ite3_blob_bytes(
35450 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
35460 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 .** ^An attempt
35470 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e 20 to read from an
35480 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 expired [BLOB ha
35490 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 ndle] fails with
354a0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 an.** error cod
354b0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f e of [SQLITE_ABO
354c0 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 RT]..**.** ^(On
354d0 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33 success, sqlite3
354e0 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20 72 65 74 _blob_read() ret
354f0 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a urns SQLITE_OK..
35500 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e ** Otherwise, an
35510 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 [error code] or
35520 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 an [extended er
35530 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
35540 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 urned.)^.**.** T
35550 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 his routine only
35560 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f works on a [BLO
35570 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 B handle] which
35580 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 has been created
35590 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 .** by a prior s
355a0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
355b0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f o [sqlite3_blob_
355c0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 open()] and whic
355d0 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 h has not.** bee
355e0 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c n closed by [sql
355f0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 ite3_blob_close(
35600 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 )]. Passing any
35610 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 other pointer i
35620 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 n.** to this rou
35630 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 tine results in
35640 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
35650 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 obably undesirab
35660 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a le behavior..**.
35670 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
35680 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 lite3_blob_write
35690 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
356a0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 te3_blob_read(sq
356b0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f lite3_blob *, vo
356c0 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e id *Z, int N, in
356d0 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a t iOffset);../*.
356e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72 69 ** CAPI3REF: Wri
356f0 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 te Data Into A B
35700 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c LOB Incrementall
35710 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 y.**.** ^This fu
35720 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 nction is used t
35730 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e 74 o write data int
35740 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 o an open [BLOB
35750 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a handle] from a.*
35760 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 * caller-supplie
35770 64 20 62 75 66 66 65 72 2e 20 5e 4e 20 62 79 74 d buffer. ^N byt
35780 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 es of data are c
35790 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 opied from the b
357a0 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 uffer Z.** into
357b0 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 the open BLOB, s
357c0 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 tarting at offse
357d0 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a t iOffset..**.**
357e0 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 ^If the [BLOB h
357f0 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 andle] passed as
35800 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
35810 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e ent was not open
35820 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e ed for.** writin
35830 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 g (the flags par
35840 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
35850 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 e3_blob_open()]
35860 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 was zero),.** th
35870 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
35880 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 rns [SQLITE_READ
35890 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ONLY]..**.** ^Th
358a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 is function may
358b0 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 only modify the
358c0 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 contents of the
358d0 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e BLOB; it is.** n
358e0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 ot possible to i
358f0 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 ncrease the size
35900 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 6e 67 of a BLOB using
35910 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 5e 49 this API..** ^I
35920 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 f offset iOffset
35930 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 is less than N
35940 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 bytes from the e
35950 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a nd of the BLOB,.
35960 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ** [SQLITE_ERROR
35970 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
35980 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 d no data is wri
35990 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20 69 73 0a tten. ^If N is.
359a0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 ** less than zer
359b0 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d o [SQLITE_ERROR]
359c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
359d0 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 no data is writ
359e0 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 ten..** The size
359f0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61 6e of the BLOB (an
35a00 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69 d hence the maxi
35a10 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 mum value of N+i
35a20 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 Offset).** can b
35a30 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 e determined usi
35a40 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ng the [sqlite3_
35a50 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e blob_bytes()] in
35a60 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e terface..**.** ^
35a70 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72 An attempt to wr
35a80 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65 ite to an expire
35a90 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 d [BLOB handle]
35aa0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a fails with an.**
35ab0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b error code of [
35ac0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 SQLITE_ABORT].
35ad0 5e 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 ^Writes to the B
35ae0 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 LOB that occurre
35af0 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 d.** before the
35b00 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 [BLOB handle] ex
35b10 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f pired are not ro
35b20 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 lled back by the
35b30 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f .** expiration o
35b40 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 f the handle, th
35b50 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 ough of course t
35b60 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 hose changes mig
35b70 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 ht.** have been
35b80 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 overwritten by t
35b90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 he statement tha
35ba0 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c t expired the BL
35bb0 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 OB handle.** or
35bc0 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e by other indepen
35bd0 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e dent statements.
35be0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 .**.** ^(On succ
35bf0 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f ess, sqlite3_blo
35c00 62 5f 77 72 69 74 65 28 29 20 72 65 74 75 72 6e b_write() return
35c10 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 s SQLITE_OK..**
35c20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20 5b Otherwise, an [
35c30 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 error code] or a
35c40 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f n [extended erro
35c50 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
35c60 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 ned.)^.**.** Thi
35c70 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 s routine only w
35c80 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 orks on a [BLOB
35c90 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 handle] which ha
35ca0 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a s been created.*
35cb0 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 * by a prior suc
35cc0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
35cd0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
35ce0 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 en()] and which
35cf0 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 has not.** been
35d00 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 closed by [sqlit
35d10 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d e3_blob_close()]
35d20 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f . Passing any o
35d30 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a ther pointer in.
35d40 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ** to this routi
35d50 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e ne results in un
35d60 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
35d70 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 ably undesirable
35d80 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a behavior..**.**
35d90 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
35da0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d te3_blob_read()]
35db0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
35dc0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 _blob_write(sqli
35dd0 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 te3_blob *, cons
35de0 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e t void *z, int n
35df0 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a , int iOffset);.
35e00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
35e10 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79 Virtual File Sy
35e20 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a stem Objects.**.
35e30 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c ** A virtual fil
35e40 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 73 esystem (VFS) is
35e50 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 an [sqlite3_vfs
35e60 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 ] object.** that
35e70 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20 SQLite uses to
35e80 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 interact.** with
35e90 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
35ea0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
35eb0 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 . Most SQLite b
35ec0 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20 uilds come with
35ed0 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 a.** single defa
35ee0 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73 20 ult VFS that is
35ef0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 appropriate for
35f00 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 the host compute
35f10 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 r..** New VFSes
35f20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 can be registere
35f30 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56 d and existing V
35f40 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65 FSes can be unre
35f50 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 gistered..** The
35f60 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 following inter
35f70 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 faces are provid
35f80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
35f90 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
35fa0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
35fb0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
35fc0 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73 a VFS given its
35fd0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 name..** ^Names
35fe0 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74 are case sensit
35ff0 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 ive..** ^Names a
36000 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 re zero-terminat
36010 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 ed UTF-8 strings
36020 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72 65 20 69 ..** ^If there i
36030 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 s no match, a NU
36040 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
36050 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 7a turned..** ^If z
36060 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 VfsName is NULL
36070 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 then the default
36080 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 64 VFS is returned
36090 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20 56 46 53 ..**.** ^New VFS
360a0 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 es are registere
360b0 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 d with sqlite3_v
360c0 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a fs_register()..*
360d0 2a 20 5e 45 61 63 68 20 6e 65 77 20 56 46 53 20 * ^Each new VFS
360e0 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 becomes the defa
360f0 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d ult VFS if the m
36100 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 akeDflt flag is
36110 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 61 6d set..** ^The sam
36120 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 e VFS can be reg
36130 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 istered multiple
36140 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 times without i
36150 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f 20 6d 61 njury..** ^To ma
36160 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 ke an existing V
36170 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 FS into the defa
36180 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 ult VFS, registe
36190 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 r it again.** wi
361a0 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 th the makeDflt
361b0 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 flag set. If tw
361c0 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 o different VFSe
361d0 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 s with the.** sa
361e0 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 me name are regi
361f0 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 stered, the beha
36200 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
36210 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 d. If a.** VFS
36220 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 is registered wi
36230 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 th a name that i
36240 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 s NULL or an emp
36250 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 ty string,.** th
36260 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
36270 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
36280 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74 65 72 20 .** ^Unregister
36290 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20 73 a VFS with the s
362a0 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 qlite3_vfs_unreg
362b0 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 ister() interfac
362c0 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 64 e..** ^(If the d
362d0 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e efault VFS is un
362e0 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 registered, anot
362f0 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65 her VFS is chose
36300 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 n as.** the defa
36310 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65 ult. The choice
36320 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53 for the new VFS
36330 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 29 5e is arbitrary.)^
36340 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 .*/.sqlite3_vfs
36350 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e *sqlite3_vfs_fin
36360 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 d(const char *zV
36370 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c fsName);.int sql
36380 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
36390 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 r(sqlite3_vfs*,
363a0 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 int makeDflt);.i
363b0 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 nt sqlite3_vfs_u
363c0 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 nregister(sqlite
363d0 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 3_vfs*);../*.**
363e0 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 CAPI3REF: Mutexe
363f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 s.**.** The SQLi
36400 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 te core uses the
36410 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 se routines for
36420 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 thread.** synchr
36430 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 onization. Thoug
36440 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e h they are inten
36450 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c ded for internal
36460 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 .** use by SQLit
36470 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e e, code that lin
36480 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 ks against SQLit
36490 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 e is.** permitte
364a0 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 d to use any of
364b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
364c0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 **.** The SQLite
364d0 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e source code con
364e0 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 tains multiple i
364f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a mplementations.*
36500 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 * of these mutex
36510 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 routines. An a
36520 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 ppropriate imple
36530 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 mentation.** is
36540 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74 selected automat
36550 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c ically at compil
36560 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68 65 20 66 e-time. ^(The f
36570 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c ollowing.** impl
36580 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 ementations are
36590 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 available in the
365a0 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a SQLite core:.**
365b0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
365c0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f SQLITE_MUTEX_
365d0 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 OS2.** <li> SQ
365e0 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 LITE_MUTEX_PTHRE
365f0 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c AD.** <li> SQL
36600 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a ITE_MUTEX_W32.**
36610 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d <li> SQLITE_M
36620 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 UTEX_NOOP.** </u
36630 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 l>)^.**.** ^The
36640 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f SQLITE_MUTEX_NOO
36650 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e P implementation
36660 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 is a set of rou
36670 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f tines.** that do
36680 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 es no real locki
36690 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70 ng and is approp
366a0 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e riate for use in
366b0 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 .** a single-thr
366c0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f eaded applicatio
366d0 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f n. ^The SQLITE_
366e0 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 MUTEX_OS2,.** SQ
366f0 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 LITE_MUTEX_PTHRE
36700 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d AD, and SQLITE_M
36710 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 UTEX_W32 impleme
36720 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 ntations.** are
36730 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 appropriate for
36740 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 use on OS/2, Uni
36750 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a x, and Windows..
36760 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 **.** ^(If SQLit
36770 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
36780 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 th the SQLITE_MU
36790 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 TEX_APPDEF prepr
367a0 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f ocessor.** macro
367b0 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 defined (with "
367c0 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 -DSQLITE_MUTEX_A
367d0 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 PPDEF=1"), then
367e0 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c no mutex.** impl
367f0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e ementation is in
36800 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20 cluded with the
36810 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73 library. In this
36820 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 case the.** app
36830 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 lication must su
36840 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 pply a custom mu
36850 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 tex implementati
36860 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 on using the.**
36870 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
36880 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 UTEX] option of
36890 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 the sqlite3_conf
368a0 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a ig() function.**
368b0 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 before calling
368c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
368d0 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 ze() or any othe
368e0 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 r public sqlite3
368f0 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 _.** function th
36900 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 at calls sqlite3
36910 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 29 5e _initialize().)^
36920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36930 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
36940 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 ) routine alloca
36950 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 tes a new.** mut
36960 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 ex and returns a
36970 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 pointer to it.
36980 5e 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e ^If it returns N
36990 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e ULL.** that mean
369a0 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 s that a mutex c
369b0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f ould not be allo
369c0 63 61 74 65 64 2e 20 20 5e 53 51 4c 69 74 65 0a cated. ^SQLite.
369d0 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 ** will unwind i
369e0 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74 ts stack and ret
369f0 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e urn an error. ^
36a00 28 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a (The argument.**
36a10 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
36a20 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 x_alloc() is one
36a30 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
36a40 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a r constants:.**.
36a50 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
36a60 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
36a70 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ST.** <li> SQLI
36a80 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
36a90 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 VE.** <li> SQLI
36aa0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
36ab0 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 MASTER.** <li>
36ac0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
36ad0 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 TIC_MEM.** <li>
36ae0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
36af0 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 ATIC_MEM2.** <li
36b00 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
36b10 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c STATIC_PRNG.** <
36b20 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
36b30 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 X_STATIC_LRU.**
36b40 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
36b50 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a EX_STATIC_LRU2.*
36b60 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
36b70 5e 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 ^The first two c
36b80 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c 49 54 45 onstants (SQLITE
36b90 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20 _MUTEX_FAST and
36ba0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 SQLITE_MUTEX_REC
36bb0 55 52 53 49 56 45 29 0a 2a 2a 20 63 61 75 73 65 URSIVE).** cause
36bc0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 sqlite3_mutex_a
36bd0 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 lloc() to create
36be0 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e .** a new mutex.
36bf0 20 20 5e 54 68 65 20 6e 65 77 20 6d 75 74 65 78 ^The new mutex
36c00 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68 is recursive wh
36c10 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f en SQLITE_MUTEX_
36c20 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 RECURSIVE.** is
36c30 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 used but not nec
36c40 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e essarily so when
36c50 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
36c60 53 54 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 ST is used..** T
36c70 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 he mutex impleme
36c80 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ntation does not
36c90 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 need to make a
36ca0 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 distinction.** b
36cb0 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 etween SQLITE_MU
36cc0 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e TEX_RECURSIVE an
36cd0 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 d SQLITE_MUTEX_F
36ce0 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a AST if it does.*
36cf0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 * not want to.
36d00 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c ^SQLite will onl
36d10 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75 y request a recu
36d20 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a rsive mutex in.*
36d30 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74 * cases where it
36d40 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e really needs on
36d50 65 2e 20 20 5e 49 66 20 61 20 66 61 73 74 65 72 e. ^If a faster
36d60 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d non-recursive m
36d70 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e utex.** implemen
36d80 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 tation is availa
36d90 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 ble on the host
36da0 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 platform, the mu
36db0 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a tex subsystem.**
36dc0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 might return su
36dd0 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 ch a mutex in re
36de0 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 sponse to SQLITE
36df0 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a _MUTEX_FAST..**.
36e00 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72 20 61 6c ** ^The other al
36e10 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 lowed parameters
36e20 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
36e30 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e 79 74 68 x_alloc() (anyth
36e40 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20 74 68 61 ing other.** tha
36e50 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 n SQLITE_MUTEX_F
36e60 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d AST and SQLITE_M
36e70 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 UTEX_RECURSIVE)
36e80 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 each return.** a
36e90 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 pointer to a st
36ea0 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e 67 atic preexisting
36eb0 20 6d 75 74 65 78 2e 20 20 5e 53 69 78 20 73 74 mutex. ^Six st
36ec0 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 atic mutexes are
36ed0 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 .** used by the
36ee0 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 current version
36ef0 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75 of SQLite. Futu
36f00 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
36f10 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 QLite.** may add
36f20 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 additional stat
36f30 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61 ic mutexes. Sta
36f40 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 20 tic mutexes are
36f50 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 for internal.**
36f60 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e use by SQLite on
36f70 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ly. Application
36f80 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 s that use SQLit
36f90 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 e mutexes should
36fa0 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 .** use only the
36fb0 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 dynamic mutexes
36fc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c returned by SQL
36fd0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f ITE_MUTEX_FAST o
36fe0 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 r.** SQLITE_MUTE
36ff0 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a X_RECURSIVE..**.
37000 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 69 66 ** ^Note that if
37010 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61 one of the dyna
37020 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65 mic mutex parame
37030 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 ters (SQLITE_MUT
37040 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 EX_FAST.** or SQ
37050 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
37060 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68 SIVE) is used th
37070 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 en sqlite3_mutex
37080 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 _alloc().** retu
37090 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20 rns a different
370a0 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63 mutex on every c
370b0 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f 72 20 74 all. ^But for t
370c0 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 he static.** mut
370d0 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61 ex types, the sa
370e0 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75 me mutex is retu
370f0 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61 rned on every ca
37100 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 ll that has.** t
37110 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d he same type num
37120 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ber..**.** ^The
37130 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 sqlite3_mutex_fr
37140 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 ee() routine dea
37150 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 llocates a previ
37160 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ously.** allocat
37170 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 ed dynamic mutex
37180 2e 20 20 5e 53 51 4c 69 74 65 20 69 73 20 63 61 . ^SQLite is ca
37190 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 reful to dealloc
371a0 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e ate every.** dyn
371b0 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 amic mutex that
371c0 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54 it allocates. T
371d0 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 he dynamic mutex
371e0 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 es must not be i
371f0 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 n.** use when th
37200 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 ey are deallocat
37210 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67 20 ed. Attempting
37220 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 to deallocate a
37230 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 static.** mutex
37240 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 results in undef
37250 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 20 ined behavior.
37260 5e 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 ^SQLite never de
37270 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 allocates.** a s
37280 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a tatic mutex..**.
37290 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
372a0 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e mutex_enter() an
372b0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
372c0 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61 try() routines a
372d0 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 ttempt.** to ent
372e0 65 72 20 61 20 6d 75 74 65 78 2e 20 20 5e 49 66 er a mutex. ^If
372f0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
37300 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 is already withi
37310 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 n the mutex,.**
37320 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
37330 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b ter() will block
37340 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 and sqlite3_mut
37350 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 ex_try() will re
37360 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 turn.** SQLITE_B
37370 55 53 59 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 USY. ^The sqlit
37380 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69 e3_mutex_try() i
37390 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
373a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 [SQLITE_OK].**
373b0 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20 upon successful
373c0 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74 65 78 65 entry. ^(Mutexe
373d0 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a s created using.
373e0 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ** SQLITE_MUTEX_
373f0 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 RECURSIVE can be
37400 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c entered multipl
37410 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 e times by the s
37420 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 ame thread..** I
37430 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68 65 n such cases the
37440 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 ,.** mutex must
37450 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71 75 be exited an equ
37460 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d al number of tim
37470 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 es before anothe
37480 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 r thread.** can
37490 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49 66 20 74 enter.)^ ^(If t
374a0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74 he same thread t
374b0 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e ries to enter an
374c0 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 y other.** kind
374d0 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 of mutex more th
374e0 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 an once, the beh
374f0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
37500 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 ed..** SQLite wi
37510 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74 ll never exhibit
37520 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f .** such behavio
37530 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 r in its own use
37540 20 6f 66 20 6d 75 74 65 78 65 73 2e 29 5e 0a 2a of mutexes.)^.*
37550 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73 79 73 74 *.** ^(Some syst
37560 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ems (for example
37570 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f , Windows 95) do
37580 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 not support the
37590 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d operation.** im
375a0 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c plemented by sql
375b0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
375c0 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 . On those syst
375d0 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 ems, sqlite3_mut
375e0 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c ex_try().** will
375f0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53 always return S
37600 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54 68 65 QLITE_BUSY. The
37610 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c SQLite core onl
37620 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 y ever uses.** s
37630 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
37640 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a () as an optimiz
37650 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 ation so this is
37660 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 acceptable beha
37670 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 vior.)^.**.** ^T
37680 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
37690 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 _leave() routine
376a0 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 exits a mutex t
376b0 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 hat was.** previ
376c0 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 ously entered by
376d0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
376e0 2e 20 20 20 5e 28 54 68 65 20 62 65 68 61 76 69 . ^(The behavi
376f0 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e or.** is undefin
37700 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 ed if the mutex
37710 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
37720 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 0a entered by the.
37730 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 ** calling threa
37740 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 72 d or is not curr
37750 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e ently allocated.
37760 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a SQLite will.**
37770 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 never do either
37780 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 .)^.**.** ^If th
37790 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 e argument to sq
377a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
377b0 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 r(), sqlite3_mut
377c0 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 ex_try(), or.**
377d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 sqlite3_mutex_le
377e0 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 ave() is a NULL
377f0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c pointer, then al
37800 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 l three routines
37810 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e 6f .** behave as no
37820 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 -ops..**.** See
37830 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d also: [sqlite3_m
37840 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 utex_held()] and
37850 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
37860 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 notheld()]..*/.s
37870 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 qlite3_mutex *sq
37880 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
37890 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c c(int);.void sql
378a0 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 ite3_mutex_free(
378b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
378c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 .void sqlite3_mu
378d0 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 tex_enter(sqlite
378e0 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 3_mutex*);.int s
378f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
37900 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 (sqlite3_mutex*)
37910 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d ;.void sqlite3_m
37920 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 utex_leave(sqlit
37930 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a e3_mutex*);../*.
37940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
37950 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 ex Methods Objec
37960 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 t.**.** An insta
37970 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 nce of this stru
37980 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74 68 cture defines th
37990 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74 e low-level rout
379a0 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 ines.** used to
379b0 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 65 allocate and use
379c0 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 mutexes..**.**
379d0 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 66 Usually, the def
379e0 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c 65 ault mutex imple
379f0 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 69 mentations provi
37a00 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 72 ded by SQLite ar
37a10 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 2c e.** sufficient,
37a20 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73 65 however the use
37a30 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f 6e r has the option
37a40 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e 67 of substituting
37a50 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 a custom.** imp
37a60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 lementation for
37a70 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70 6c specialized depl
37a80 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 65 oyments or syste
37a90 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51 4c ms for which SQL
37aa0 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 ite.** does not
37ab0 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61 62 provide a suitab
37ac0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
37ad0 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c n. In this case,
37ae0 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 65 the user.** cre
37af0 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 74 ates and populat
37b00 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f es an instance o
37b10 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 f this structure
37b20 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20 73 to pass.** to s
37b30 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
37b40 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20 5b along with the [
37b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
37b60 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 TEX] option..**
37b70 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e Additionally, an
37b80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
37b90 73 20 73 74 72 75 63 74 75 72 65 20 63 61 6e 20 s structure can
37ba0 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a 2a be used as an.**
37bb0 20 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c 65 output variable
37bc0 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20 74 when querying t
37bd0 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74 68 he system for th
37be0 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78 0a e current mutex.
37bf0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
37c00 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 n, using the [SQ
37c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
37c20 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a UTEX] option..**
37c30 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 .** ^The xMutexI
37c40 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69 6e nit method defin
37c50 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 ed by this struc
37c60 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 ture is invoked
37c70 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 as.** part of sy
37c80 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74 stem initializat
37c90 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 ion by the sqlit
37ca0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
37cb0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 function..** ^Th
37cc0 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 e xMutexInit rou
37cd0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 20 62 79 tine is calle by
37ce0 20 53 51 4c 69 74 65 20 65 78 61 63 74 6c 79 20 SQLite exactly
37cf0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a once for each.**
37d00 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 effective call
37d10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 to [sqlite3_init
37d20 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a ialize()]..**.**
37d30 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20 ^The xMutexEnd
37d40 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 method defined b
37d50 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 y this structure
37d60 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a is invoked as.*
37d70 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d * part of system
37d80 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65 shutdown by the
37d90 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
37da0 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 n() function. Th
37db0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
37dc0 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68 ion of this meth
37dd0 6f 64 20 69 73 20 65 78 70 65 63 74 65 64 20 74 od is expected t
37de0 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 o release all ou
37df0 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 tstanding.** res
37e00 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20 ources obtained
37e10 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 by the mutex met
37e20 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 hods implementat
37e30 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a ion, especially.
37e40 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 ** those obtaine
37e50 64 20 62 79 20 74 68 65 20 78 4d 75 74 65 78 49 d by the xMutexI
37e60 6e 69 74 20 6d 65 74 68 6f 64 2e 20 20 5e 54 68 nit method. ^Th
37e70 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a e xMutexEnd().**
37e80 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e interface is in
37e90 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e voked exactly on
37ea0 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c ce for each call
37eb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 to [sqlite3_shu
37ec0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 tdown()]..**.**
37ed0 5e 28 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 ^(The remaining
37ee0 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 seven methods de
37ef0 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 fined by this st
37f00 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 41 ructure (xMutexA
37f10 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 lloc,.** xMutexF
37f20 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 ree, xMutexEnter
37f30 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 , xMutexTry, xMu
37f40 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 texLeave, xMutex
37f50 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 Held and.** xMut
37f60 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 exNotheld) imple
37f70 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 ment the followi
37f80 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 72 ng interfaces (r
37f90 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a espectively):.**
37fa0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c .** <ul>.** <l
37fb0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
37fc0 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 ex_alloc()] </li
37fd0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
37fe0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 lite3_mutex_free
37ff0 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
38000 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
38010 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c tex_enter()] </l
38020 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
38030 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
38040 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
38050 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
38060 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c tex_leave()] </l
38070 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
38080 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c qlite3_mutex_hel
38090 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 d()] </li>.**
380a0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
380b0 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 utex_notheld()]
380c0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e </li>.** </ul>)^
380d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 .**.** The only
380e0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 74 68 difference is th
380f0 61 74 20 74 68 65 20 70 75 62 6c 69 63 20 73 71 at the public sq
38100 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69 lite3_XXX functi
38110 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a ons enumerated.*
38120 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 * above silently
38130 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f ignore any invo
38140 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73 cations that pas
38150 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
38160 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 instead.** of a
38170 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e valid mutex han
38180 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 dle. The impleme
38190 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
381a0 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a methods defined.
381b0 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72 75 63 ** by this struc
381c0 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71 ture are not req
381d0 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 uired to handle
381e0 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 72 this case, the r
381f0 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 esults.** of pas
38200 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e sing a NULL poin
38210 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 ter instead of a
38220 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e valid mutex han
38230 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 dle are undefine
38240 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 d.** (i.e. it is
38250 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70 acceptable to p
38260 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d rovide an implem
38270 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65 entation that se
38280 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 gfaults if.** it
38290 20 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c is passed a NUL
382a0 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2a 0a 2a L pointer)..**.*
382b0 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 * The xMutexInit
382c0 28 29 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 62 () method must b
382d0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 5e e threadsafe. ^
382e0 49 74 20 6d 75 73 74 20 62 65 20 68 61 72 6d 6c It must be harml
382f0 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 ess to.** invoke
38300 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 xMutexInit() mu
38310 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 tiple times with
38320 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 in the same proc
38330 65 73 73 20 61 6e 64 20 77 69 74 68 6f 75 74 0a ess and without.
38340 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 63 ** intervening c
38350 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65 78 45 6e alls to xMutexEn
38360 64 28 29 2e 20 20 53 65 63 6f 6e 64 20 61 6e 64 d(). Second and
38370 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
38380 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65 78 49 6e s to.** xMutexIn
38390 69 74 28 29 20 6d 75 73 74 20 62 65 20 6e 6f 2d it() must be no-
383a0 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 78 4d 75 74 ops..**.** ^xMut
383b0 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 6e 6f exInit() must no
383c0 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d t use SQLite mem
383d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 ory allocation (
383e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
383f0 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73 20 61 73 )].** and its as
38400 73 6f 63 69 61 74 65 73 29 2e 20 20 5e 53 69 6d sociates). ^Sim
38410 69 6c 61 72 6c 79 2c 20 78 4d 75 74 65 78 41 6c ilarly, xMutexAl
38420 6c 6f 63 28 29 20 6d 75 73 74 20 6e 6f 74 20 75 loc() must not u
38430 73 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 se SQLite memory
38440 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 .** allocation f
38450 6f 72 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 or a static mute
38460 78 2e 20 20 5e 48 6f 77 65 76 65 72 20 78 4d 75 x. ^However xMu
38470 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61 79 20 75 texAlloc() may u
38480 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 65 6d se SQLite.** mem
38490 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
384a0 6f 72 20 61 20 66 61 73 74 20 6f 72 20 72 65 63 or a fast or rec
384b0 75 72 73 69 76 65 20 6d 75 74 65 78 2e 0a 2a 2a ursive mutex..**
384c0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
384d0 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 4d 75 74 invoke the xMut
384e0 65 78 45 6e 64 28 29 20 6d 65 74 68 6f 64 20 77 exEnd() method w
384f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 hen [sqlite3_shu
38500 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a 2a 20 63 tdown()] is.** c
38510 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e 6c 79 20 alled, but only
38520 69 66 20 74 68 65 20 70 72 69 6f 72 20 63 61 6c if the prior cal
38530 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e 69 74 20 l to xMutexInit
38540 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54 45 5f returned SQLITE_
38550 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75 74 65 78 OK..** If xMutex
38560 49 6e 69 74 20 66 61 69 6c 73 20 69 6e 20 61 6e Init fails in an
38570 79 20 77 61 79 2c 20 69 74 20 69 73 20 65 78 70 y way, it is exp
38580 65 63 74 65 64 20 74 6f 20 63 6c 65 61 6e 20 75 ected to clean u
38590 70 20 61 66 74 65 72 20 69 74 73 65 6c 66 0a 2a p after itself.*
385a0 2a 20 70 72 69 6f 72 20 74 6f 20 72 65 74 75 72 * prior to retur
385b0 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ning..*/.typedef
385c0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
385d0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73 71 mutex_methods sq
385e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
385f0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
38600 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
38610 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 s {. int (*xMut
38620 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a 20 exInit)(void);.
38630 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e 64 int (*xMutexEnd
38640 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69 74 )(void);. sqlit
38650 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74 e3_mutex *(*xMut
38660 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a 20 exAlloc)(int);.
38670 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46 72 void (*xMutexFr
38680 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ee)(sqlite3_mute
38690 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 x *);. void (*x
386a0 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c 69 MutexEnter)(sqli
386b0 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 te3_mutex *);.
386c0 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79 29 int (*xMutexTry)
386d0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
386e0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 );. void (*xMut
386f0 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65 33 exLeave)(sqlite3
38700 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 _mutex *);. int
38710 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28 73 (*xMutexHeld)(s
38720 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b qlite3_mutex *);
38730 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 4e . int (*xMutexN
38740 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33 5f otheld)(sqlite3_
38750 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a mutex *);.};../*
38760 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 .** CAPI3REF: Mu
38770 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f 6e tex Verification
38780 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 Routines.**.**
38790 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
387a0 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c x_held() and sql
387b0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 ite3_mutex_nothe
387c0 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a ld() routines.**
387d0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
387e0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 r use inside ass
387f0 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 ert() statements
38800 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 . ^The SQLite c
38810 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 ore.** never use
38820 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 s these routines
38830 20 65 78 63 65 70 74 20 69 6e 73 69 64 65 20 61 except inside a
38840 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64 20 61 n assert() and a
38850 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 pplications.** a
38860 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f re advised to fo
38870 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66 llow the lead of
38880 20 74 68 65 20 63 6f 72 65 2e 20 20 5e 54 68 65 the core. ^The
38890 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c SQLite core onl
388a0 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d y.** provides im
388b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
388c0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 r these routines
388d0 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 when it is comp
388e0 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 iled.** with the
388f0 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c SQLITE_DEBUG fl
38900 61 67 2e 20 20 5e 45 78 74 65 72 6e 61 6c 20 6d ag. ^External m
38910 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74