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 61 74 65 73 20 74 6f 0a ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 in of SQLite.**
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 ent system. ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 h of the entire
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 sourceid()],.**
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d ERSION "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 ID "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 information as
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a . ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 nterfaces match
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e>)^.**.** ^The
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 ction returns a
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 g constant. The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 e DLL. ^The.**
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 tion returns an
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 ION_NUMBER]. ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 constant whose
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 LITE_SOURCE_ID]
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 acro..**.** See
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 ceid(void);.int
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 * compile time.
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 d(). .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 nction allows it
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: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 compile_options
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 OptName);.const
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e ]. ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 ng of.** thread
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 safety, not any
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 ach open SQLite
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 amed "sqlite3".
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ite3.** pointer
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 as an object. T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 en16()], and.**
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 3_close()].** is
23f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e its destructor.
2400: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 There are many
2410: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 other interface
2420: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 s (such as.** [s
2430: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2440: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 2()], [sqlite3_c
2450: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
2460: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
2470: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
2480: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 )] to name but t
2490: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d hree) that are m
24a0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 ethods on an.**
24b0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a sqlite3 object..
24c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
24d0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 t sqlite3 sqlite
24e0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3;../*.** CAPI3R
24f0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 EF: 64-Bit Integ
2500: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 er Types.** KEYW
2510: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 ORDS: sqlite_int
2520: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 64 sqlite_uint64
2530: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
2540: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 here is no cross
2550: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f -platform way to
2560: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 specify 64-bit
2570: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a integer types.**
2580: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 SQLite includes
2590: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 typedefs for 64
25a0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 -bit signed and
25b0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 unsigned integer
25c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
25d0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 ite3_int64 and s
25e0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 qlite3_uint64 ar
25f0: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 e the preferred
2600: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 type definitions
2610: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f ..** The sqlite_
2620: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2630: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 _uint64 types ar
2640: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 e supported for
2650: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d backwards.** com
2660: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e patibility only.
2670: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2680: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 te3_int64 and sq
2690: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 lite_int64 types
26a0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 can store integ
26b0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 er values.** bet
26c0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 ween -9223372036
26d0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 854775808 and +9
26e0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 2233720368547758
26f0: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 07 inclusive. ^
2700: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 The.** sqlite3_u
2710: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2720: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 _uint64 types ca
2730: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 n store integer
2740: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 values .** betwe
2750: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 en 0 and +184467
2760: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 44073709551615 i
2770: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 nclusive..*/.#if
2780: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
2790: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 _TYPE. typedef
27a0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
27b0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a E sqlite_int64;.
27c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
27d0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ed SQLITE_INT64_
27e0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 TYPE sqlite_uint
27f0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64;.#elif define
2800: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 d(_MSC_VER) || d
2810: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 efined(__BORLAND
2820: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f C__). typedef _
2830: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e _int64 sqlite_in
2840: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
2850: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 nsigned __int64
2860: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
2870: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c else. typedef l
2880: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
2890: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
28a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f edef unsigned lo
28b0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 ng long int sqli
28c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 te_uint64;.#endi
28d0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 f.typedef sqlite
28e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 _int64 sqlite3_i
28f0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 nt64;.typedef sq
2900: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 lite_uint64 sqli
2910: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a te3_uint64;../*.
2920: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 ** If compiling
2930: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 for a processor
2940: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 that lacks float
2950: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 ing point suppor
2960: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 t,.** substitute
2970: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f integer for flo
2980: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a ating-point..*/.
2990: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d #ifdef SQLITE_OM
29a0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e IT_FLOATING_POIN
29b0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c T.# define doubl
29c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a e sqlite3_int64.
29d0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
29e0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 PI3REF: Closing
29f0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 A Database Conne
2a00: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ction.**.** ^The
2a10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2a20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 routine is the
2a30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 destructor for t
2a40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
2a50: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ect..** ^Calls t
2a60: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 o sqlite3_close(
2a70: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f ) return SQLITE_
2a80: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 OK if the [sqlit
2a90: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a e3] object is.**
2aa0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 successfully de
2ab0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 stroyed and all
2ac0: 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 associated resou
2ad0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 rces are dealloc
2ae0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c ated..**.** Appl
2af0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73 ications must [s
2b00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 qlite3_finalize
2b10: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 | finalize] all
2b20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2b30: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 ents].** and [sq
2b40: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
2b50: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 | close] all [B
2b60: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 LOB handles] ass
2b70: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 ociated with.**
2b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
2b90: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 ject prior to at
2ba0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 tempting to clos
2bb0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e e the object. ^
2bc0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c If.** sqlite3_cl
2bd0: 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ose() is called
2be0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 on a [database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 onnection] that
2c00: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 still has.** out
2c10: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 standing [prepar
2c20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f ed statements] o
2c30: 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d r [BLOB handles]
2c40: 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e , then it return
2c50: 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 s.** SQLITE_BUSY
2c60: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c ..**.** ^If [sql
2c70: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 ite3_close()] is
2c80: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 invoked while a
2c90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
2ca0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 open,.** the tra
2cb0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f nsaction is auto
2cc0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
2cd0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 back..**.** The
2ce0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 C parameter to
2cf0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 [sqlite3_close(C
2d00: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 )] must be eithe
2d10: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e r a NULL.** poin
2d20: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 ter or an [sqlit
2d30: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 e3] object point
2d40: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 er obtained.** f
2d50: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 rom [sqlite3_ope
2d60: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
2d70: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 pen16()], or.**
2d80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
2d90: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 ()], and not pre
2da0: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a viously closed..
2db0: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 ** ^Calling sqli
2dc0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68 te3_close() with
2dd0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
2de0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a argument is a .*
2df0: 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 * harmless no-op
2e00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2e10: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a _close(sqlite3 *
2e20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 );../*.** The ty
2e30: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 pe for a callbac
2e40: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 k function..** T
2e50: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e his is legacy an
2e60: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 d deprecated. I
2e70: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f t is included fo
2e80: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 r historical.**
2e90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e compatibility an
2ea0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e d is not documen
2eb0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ted..*/.typedef
2ec0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 int (*sqlite3_ca
2ed0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
2ee0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a t,char**, char**
2ef0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2f00: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 EF: One-Step Que
2f10: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 ry Execution Int
2f20: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 erface.**.** The
2f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
2f40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 interface is a c
2f50: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 onvenience wrapp
2f60: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 er around.** [sq
2f70: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2f80: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
2f90: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 ep()], and [sqli
2fa0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c te3_finalize()],
2fb0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 .** that allows
2fc0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 an application t
2fd0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 o run multiple s
2fe0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c tatements of SQL
2ff0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 .** without havi
3000: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 ng to use a lot
3010: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a of C code. .**.*
3020: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
3030: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 xec() interface
3040: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 runs zero or mor
3050: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c e UTF-8 encoded,
3060: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 .** semicolon-se
3070: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 parate SQL state
3080: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 ments passed int
3090: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 o its 2nd argume
30a0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f nt,.** in the co
30b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 ntext of the [da
30c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
30d0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 n] passed in as
30e0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d its 1st.** argum
30f0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 ent. ^If the ca
3100: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
3110: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d of the 3rd argum
3120: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 ent to.** sqlite
3130: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 3_exec() is not
3140: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 NULL, then it is
3150: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 invoked for eac
3160: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 h result row.**
3170: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 coming out of th
3180: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 e evaluated SQL
3190: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 statements. ^Th
31a0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 e 4th argument t
31b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
31c0: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 c() is relayed t
31d0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 hrough to the 1s
31e0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 t argument of ea
31f0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 ch.** callback i
3200: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 nvocation. ^If
3210: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 the callback poi
3220: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f nter to sqlite3_
3230: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c exec().** is NUL
3240: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 L, then no callb
3250: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f ack is ever invo
3260: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 ked and result r
3270: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 ows are.** ignor
3280: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ed..**.** ^If an
3290: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
32a0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 ile evaluating t
32b0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
32c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a s passed into.**
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c sqlite3_exec(),
32e0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 then execution
32f0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 of the current s
3300: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 tatement stops a
3310: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 nd.** subsequent
3320: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
3330: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 skipped. ^If th
3340: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
3350: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
3360: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c ).** is not NULL
3370: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 then any error
3380: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 message is writt
3390: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f en into memory o
33a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
33b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
33c0: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 )] and passed ba
33d0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 ck through the 5
33e0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a th parameter..**
33f0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 To avoid memory
3400: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c leaks, the appl
3410: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 ication should i
3420: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 nvoke [sqlite3_f
3430: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 ree()].** on err
3440: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
3450: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f gs returned thro
3460: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 ugh the 5th para
3470: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 meter of.** of s
3480: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 qlite3_exec() af
3490: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 ter the error me
34a0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
34b0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 no longer needed
34c0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 ..** ^If the 5th
34d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
34e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
34f0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 not NULL and no
3500: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c errors.** occur,
3510: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 then sqlite3_ex
3520: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f ec() sets the po
3530: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 inter in its 5th
3540: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
3550: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 NULL before ret
3560: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 urning..**.** ^I
3570: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 f an sqlite3_exe
3580: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 c() callback ret
3590: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
35a0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
35b0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
35c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 urns SQLITE_ABOR
35d0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 T without invoki
35e0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 ng the callback
35f0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 again and.** wit
3600: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 hout running any
3610: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 subsequent SQL
3620: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
3630: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d * ^The 2nd argum
3640: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
3650: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
3660: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ck function is t
3670: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
3680: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
3690: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 esult. ^The 3rd
36a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
36b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
36c0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 ** callback is a
36d0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
36e0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f ers to strings o
36f0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 btained as if fr
3700: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 om.** [sqlite3_c
3710: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f olumn_text()], o
3720: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 ne for each colu
3730: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d mn. ^If an elem
3740: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 ent of a.** resu
3750: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 lt row is NULL t
3760: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
3770: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 nding string poi
3780: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 nter for the.**
3790: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 sqlite3_exec() c
37a0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c allback is a NUL
37b0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 L pointer. ^The
37c0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
37d0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f the.** sqlite3_
37e0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
37f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
3800: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
3810: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a gs where each.**
3820: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 entry represent
3830: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f s the name of co
3840: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 rresponding resu
3850: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 lt column as obt
3860: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
3870: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
3880: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 me()]..**.** ^If
3890: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
38a0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
38b0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 ec() is a NULL p
38c0: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 ointer, a pointe
38d0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 r.** to an empty
38e0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f string, or a po
38f0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 inter that conta
3900: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 ins only whitesp
3910: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 ace and/or .** S
3920: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 QL comments, the
3930: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 n no SQL stateme
3940: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 nts are evaluate
3950: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 d and the databa
3960: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 se.** is not cha
3970: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 nged..**.** Rest
3980: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 rictions:.**.**
3990: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
39a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
39b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 t insure that th
39c0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
39d0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
39e0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 ).** is a v
39f0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 alid and open [d
3a00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3a10: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 on]..** <li> The
3a20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
3a30: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 t not close [dat
3a40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a50: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a ] specified by.*
3a60: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 * the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 te3_exec() while
3a90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3aa0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c is running..** <
3ab0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
3ac0: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 ion must not mod
3ad0: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 ify the SQL stat
3ae0: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 ement text passe
3af0: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 d into.** t
3b00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
3b10: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 of sqlite3_exec
3b20: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 () while sqlite3
3b30: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 _exec() is runni
3b40: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a ng..** </ul>.*/.
3b50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 int sqlite3_exec
3b60: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 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 20 20 2f /
3b90: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 * An open databa
3ba0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 se */. const ch
3bb0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 ar *sql,
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3bd0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 /* SQL to be
3be0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 evaluated */. i
3bf0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 nt (*callback)(v
3c00: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c oid*,int,char**,
3c10: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c char**), /* Cal
3c20: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a lback function *
3c30: 2f 0a 20 20 76 6f 69 64 20 2a 2c 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 20 20 2f /
3c60: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 * 1st argument t
3c70: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 o callback */.
3c80: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 char **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 20 20 2f 2a 20 45 72 /* Er
3cb0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 ror msg written
3cc0: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a here */.);../*.*
3cd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 * CAPI3REF: Resu
3ce0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 lt Codes.** KEYW
3cf0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 ORDS: SQLITE_OK
3d00: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 {error code} {er
3d10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 ror codes}.** KE
3d20: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 YWORDS: {result
3d30: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f code} {result co
3d40: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 des}.**.** Many
3d50: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 SQLite functions
3d60: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 return an integ
3d70: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 er result code f
3d80: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 rom the set show
3d90: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 n.** here in ord
3da0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 er to indicate s
3db0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 uccess or failur
3dc0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 e..**.** New err
3dd0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 or codes may be
3de0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
3df0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
3e00: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c te..**.** See al
3e10: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 so: [SQLITE_IOER
3e20: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 R_READ | extende
3e30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c d result codes],
3e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 .** [sqlite3_vta
3e50: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d b_on_conflict()]
3e60: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 [SQLITE_ROLLBAC
3e70: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 K | result codes
3e80: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ]..*/.#define SQ
3e90: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 LITE_OK
3ea0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 0 /* Success
3eb0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a ful result */./*
3ec0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 beginning-of-er
3ed0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 ror-codes */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f fine SQLITE_ERRO
3ef0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 R 1 /*
3f00: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 SQL error or mis
3f10: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f sing database */
3f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3f30: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 INTERNAL 2
3f40: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 /* Internal log
3f50: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 ic error in SQLi
3f60: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 te */.#define SQ
3f70: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 LITE_PERM
3f80: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 3 /* Access
3f90: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 permission denie
3fa0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
3fb0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 ITE_ABORT
3fc0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 4 /* Callback
3fd0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 routine request
3fe0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 ed an abort */.#
3ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 define SQLITE_BU
4000: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f SY 5 /
4010: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 * The database f
4020: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f ile is locked */
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4040: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 LOCKED 6
4050: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 /* A table in t
4060: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c he database is l
4070: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ocked */.#define
4080: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 SQLITE_NOMEM
4090: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 7 /* A ma
40a0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f lloc() failed */
40b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
40c0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 READONLY 8
40d0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 /* Attempt to w
40e0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 rite a readonly
40f0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 database */.#def
4100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 ine SQLITE_INTER
4110: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f RUPT 9 /* O
4120: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 peration termina
4130: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 ted by sqlite3_i
4140: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 nterrupt()*/.#de
4150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4160: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 R 10 /*
4170: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 Some kind of dis
4180: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 k I/O error occu
4190: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rred */.#define
41a0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 SQLITE_CORRUPT
41b0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 11 /* The d
41c0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 atabase disk ima
41d0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 ge is malformed
41e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
41f0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 E_NOTFOUND 12
4200: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 /* Unknown op
4210: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f code in sqlite3_
4220: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a file_control() *
4230: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4240: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 _FULL 13
4250: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 /* Insertion f
4260: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 ailed because da
4270: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a tabase is full *
4280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4290: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 _CANTOPEN 14
42a0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f /* Unable to o
42b0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
42c0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 file */.#define
42d0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c SQLITE_PROTOCOL
42e0: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 15 /* Data
42f0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 base lock protoc
4300: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 ol error */.#def
4310: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 ine SQLITE_EMPTY
4320: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 16 /* D
4330: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 atabase is empty
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4350: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 TE_SCHEMA 1
4360: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 7 /* The datab
4370: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 ase schema chang
4380: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
4390: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 LITE_TOOBIG
43a0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 18 /* String
43b0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 or BLOB exceeds
43c0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 size limit */.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
43e0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a STRAINT 19 /*
43f0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f Abort due to co
4400: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
4410: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 on */.#define SQ
4420: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 LITE_MISMATCH
4430: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 20 /* Data ty
4440: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 pe mismatch */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 define SQLITE_MI
4460: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f SUSE 21 /
4470: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 * Library used i
4480: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 ncorrectly */.#d
4490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c efine SQLITE_NOL
44a0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a FS 22 /*
44b0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 Uses OS feature
44c0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 s not supported
44d0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 on host */.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 ne SQLITE_AUTH
44f0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 23 /* Au
4500: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 thorization deni
4510: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
4520: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 LITE_FORMAT
4530: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 24 /* Auxilia
4540: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d ry database form
4550: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 at error */.#def
4560: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 ine SQLITE_RANGE
4570: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 25 /* 2
4580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
4590: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 sqlite3_bind out
45a0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 of range */.#de
45b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 fine SQLITE_NOTA
45c0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 DB 26 /*
45d0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 File opened that
45e0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 is not a databa
45f0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 se file */.#defi
4600: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 ne SQLITE_ROW
4610: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 100 /* sq
4620: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 lite3_step() has
4630: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 another row rea
4640: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 dy */.#define SQ
4650: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 LITE_DONE
4660: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 101 /* sqlite3
4670: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 _step() has fini
4680: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a shed executing *
4690: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f /./* end-of-erro
46a0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a r-codes */../*.*
46b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 * CAPI3REF: Exte
46c0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 nded Result Code
46d0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
46e0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
46f0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 ode} {extended e
4700: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b rror codes}.** K
4710: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 EYWORDS: {extend
4720: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 ed result code}
4730: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 {extended result
4740: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e codes}.**.** In
4750: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e its default con
4760: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 figuration, SQLi
4770: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 te API routines
4780: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 return one of 26
4790: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c integer.** [SQL
47a0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 ITE_OK | result
47b0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 codes]. However
47c0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 , experience has
47d0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 shown that many
47e0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 of.** these res
47f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f ult codes are to
4800: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 o coarse-grained
4810: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 . They do not p
4820: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 rovide as.** muc
4830: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 h information ab
4840: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 out problems as
4850: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 programmers migh
4860: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 t like. In an e
4870: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 ffort to.** addr
4880: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 ess this, newer
4890: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
48a0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e te (version 3.3.
48b0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 8 and later) inc
48c0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 lude.** support
48d0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 for additional r
48e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 esult codes that
48f0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 provide more de
4900: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 tailed informati
4910: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f on.** about erro
4920: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 rs. The extended
4930: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
4940: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 e enabled or dis
4950: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 abled.** on a pe
4960: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
4970: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e ction basis usin
4980: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
4990: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
49a0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a t_codes()] API..
49b0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 **.** Some of th
49c0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 e available exte
49d0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
49e0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 s are listed her
49f0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 e..** One may ex
4a00: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 pect the number
4a10: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 of extended resu
4a20: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 lt codes will be
4a30: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 expand.** over
4a40: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 time. Software
4a50: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 that uses extend
4a60: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
4a70: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a should expect.**
4a80: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 to see new resu
4a90: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 lt codes in futu
4aa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
4ab0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 QLite..**.** The
4ac0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c SQLITE_OK resul
4ad0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 t code will neve
4ae0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 r be extended.
4af0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a It will always.*
4b00: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 * be exactly zer
4b10: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 o..*/.#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 LITE_IOERR_READ
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c LITE_IOERR | (1<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f ITE_IOERR_SHORT_
4b70: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c READ (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c ITE_IOERR | (2<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 TE_IOERR_WRITE
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 TE_IOERR | (3<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 E_IOERR_FSYNC
4bf0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 E_IOERR | (4<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 _IOERR_DIR_FSYNC
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 _IOERR | (5<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4c60: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 IOERR_TRUNCATE
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a IOERR | (6<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4ca0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 OERR_FSTAT
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 OERR | (7<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4ce0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 ERR_UNLOCK
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 ERR | (8<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4d20: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 RR_RDLOCK
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4d40: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 RR | (9<<8)).#de
4d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4d60: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 R_DELETE
4d70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4d80: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 R | (10<<8)).#de
4d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4da0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 R_BLOCKED
4db0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4dc0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 R | (11<<8)).#de
4dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4de0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 R_NOMEM
4df0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4e00: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 R | (12<<8)).#de
4e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4e20: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 R_ACCESS
4e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4e40: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 R | (13<<8)).#de
4e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4e60: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c R_CHECKRESERVEDL
4e70: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 OCK (SQLITE_IOER
4e80: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 R | (14<<8)).#de
4e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4ea0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 R_LOCK
4eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4ec0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 R | (15<<8)).#de
4ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 R_CLOSE
4ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4f00: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 R | (16<<8)).#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4f20: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 R_DIR_CLOSE
4f30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4f40: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 R | (17<<8)).#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4f60: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 R_SHMOPEN
4f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4f80: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 R | (18<<8)).#de
4f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4fa0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 R_SHMSIZE
4fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4fc0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 R | (19<<8)).#de
4fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4fe0: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 R_SHMLOCK
4ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5000: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 R | (20<<8)).#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5020: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 R_SHMMAP
5030: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5040: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 R | (21<<8)).#de
5050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5060: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 R_SEEK
5070: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5080: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 R | (22<<8)).#de
5090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
50a0: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 ED_SHAREDCACHE
50b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b (SQLITE_LOCK
50c0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 ED | (1<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
50e0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 Y_RECOVERY
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 (SQLITE_BUS
5100: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 Y | (1<<8)).#
5110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
5120: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 NTOPEN_NOTEMPDIR
5130: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
5140: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 NTOPEN | (1<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5160: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 CORRUPT_VTAB
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5180: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 CORRUPT | (1<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
51a0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 _READONLY_RECOVE
51b0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 RY (SQLITE
51c0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c _READONLY | (1<<
51d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
51e0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 TE_READONLY_CANT
51f0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 LOCK (SQLI
5200: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 TE_READONLY | (2
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5220: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 LITE_ABORT_ROLLB
5230: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 ACK (SQ
5240: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c LITE_ABORT | (2<
5250: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 <8))../*.** CAPI
5260: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 3REF: Flags For
5270: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 File Open Operat
5280: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
5290: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 bit values are
52a0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
52b0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 in the.** 3rd p
52c0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
52d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
52e0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e ()] interface an
52f0: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 d.** in the 4th
5300: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
5310: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
5320: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a pen] method..*/.
5330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5340: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 PEN_READONLY
5350: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 0x00000001
5360: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
5370: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
5380: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5390: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 PEN_READWRITE
53a0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 0x00000002
53b0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
53c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
53d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
53e0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 PEN_CREATE
53f0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 0x00000004
5400: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
5410: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
5420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5430: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
5440: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 E 0x00000008
5450: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
5460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5470: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 PEN_EXCLUSIVE
5480: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 0x00000010
5490: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
54a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
54b0: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 PEN_AUTOPROXY
54c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 0x00000020
54d0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
54e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
54f0: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 PEN_URI
5500: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 0x00000040
5510: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
5520: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
5530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5540: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 PEN_MAIN_DB
5550: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 0x00000100
5560: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
5570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5580: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 PEN_TEMP_DB
5590: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 0x00000200
55a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
55b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
55c0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 PEN_TRANSIENT_DB
55d0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 0x00000400
55e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
55f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5600: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c PEN_MAIN_JOURNAL
5610: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 0x00000800
5620: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
5630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5640: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c PEN_TEMP_JOURNAL
5650: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 0x00001000
5660: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
5670: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5680: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 PEN_SUBJOURNAL
5690: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 0x00002000
56a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
56b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
56c0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
56d0: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 AL 0x00004000
56e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
56f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5700: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 PEN_NOMUTEX
5710: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 0x00008000
5720: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
5730: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
5740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5750: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 PEN_FULLMUTEX
5760: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 0x00010000
5770: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
5780: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
5790: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
57a0: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 PEN_SHAREDCACHE
57b0: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 0x00020000
57c0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
57d0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
57e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
57f0: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
5800: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 0x00040000
5810: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
5820: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
5830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5840: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 PEN_WAL
5850: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 0x00080000
5860: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
5870: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 ./* Reserved:
5880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5890: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 0x00F00000
58a0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
58b0: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 REF: Device Char
58c0: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a acteristics.**.*
58d0: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 * The xDeviceCha
58e0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 racteristics met
58f0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 hod of the [sqli
5900: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a te3_io_methods].
5910: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e ** object return
5920: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
5930: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f ch is a vector o
5940: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 f the these.** b
5950: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 it values expres
5960: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 sing I/O charact
5970: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 eristics of the
5980: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 mass storage.**
5990: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 device that hold
59a0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 s the file that
59b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
59c0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 methods].** refe
59d0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rs to..**.** The
59e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
59f0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
5a00: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
5a10: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
5a20: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
5a30: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
5a40: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
5a50: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
5a60: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
5a70: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
5a80: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
5a90: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
5aa0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
5ab0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
5ac0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
5ad0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
5ae0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
5af0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
5b00: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
5b10: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
5b20: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
5b30: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
5b40: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
5b50: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
5b60: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
5b70: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
5b80: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
5b90: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
5ba0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
5bb0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
5bc0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
5bd0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
5be0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
5bf0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
5c00: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
5c10: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f (). The SQLITE_
5c20: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
5c30: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 OVERWRITE proper
5c40: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
5c50: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f after reboot fo
5c60: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 llowing a crash
5c70: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 or power loss, t
5c80: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e he only bytes in
5c90: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 a.** file that
5ca0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 were written at
5cb0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
5cc0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 level might have
5cd0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 changed.** and
5ce0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 that adjacent by
5cf0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 tes, even bytes
5d00: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
5d10: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 sector are.** gu
5d20: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 aranteed to be u
5d30: 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 nchanged..*/.#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
5d50: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 P_ATOMIC
5d60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
5d70: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 001.#define SQLI
5d80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 TE_IOCAP_ATOMIC5
5d90: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 12
5da0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 0x00000002.#defi
5db0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5dc0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 ATOMIC1K
5dd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5de0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
5df0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 _IOCAP_ATOMIC2K
5e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
5e10: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 00000008.#define
5e20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5e30: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 OMIC4K
5e40: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 0x00000010.
5e50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5e60: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 OCAP_ATOMIC8K
5e70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
5e80: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 000020.#define S
5e90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5ea0: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 IC16K
5eb0: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 0x00000040.#d
5ec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5ed0: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 AP_ATOMIC32K
5ee0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5ef0: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0080.#define SQL
5f00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
5f10: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 64K
5f20: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 0x00000100.#def
5f30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5f40: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 _SAFE_APPEND
5f50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 0x000002
5f60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
5f70: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
5f80: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 AL 0
5f90: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e x00000400.#defin
5fa0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 e SQLITE_IOCAP_U
5fb0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
5fc0: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 OPEN 0x00000800
5fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5fe0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
5ff0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 OVERWRITE 0x0
6000: 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0001000../*.** C
6010: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f API3REF: File Lo
6020: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a cking Levels.**.
6030: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f ** SQLite uses o
6040: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
6050: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
6060: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 e second.** argu
6070: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 ment to calls it
6080: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c makes to the xL
6090: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
60a0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f k() methods.** o
60b0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f f an [sqlite3_io
60c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
60d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
60e0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 ITE_LOCK_NONE
60f0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
6100: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 SQLITE_LOCK_SHA
6110: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 RED 1.#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
6130: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 _RESERVED 2
6140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6150: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 LOCK_PENDING
6160: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
6170: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
6180: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 VE 4../*.**
6190: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 CAPI3REF: Synchr
61a0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 onization Type F
61b0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 lags.**.** When
61c0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 SQLite invokes t
61d0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f he xSync() metho
61e0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 d of an.** [sqli
61f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
6200: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 object it uses a
6210: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a combination of.
6220: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 ** these integer
6230: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
6240: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a econd argument..
6250: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 **.** When the S
6260: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
6270: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 NLY flag is used
6280: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
6290: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 the.** sync oper
62a0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 ation only needs
62b0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 to flush data t
62c0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 o mass storage.
62d0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d Inode.** inform
62e0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 ation need not b
62f0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 e flushed. If th
6300: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
6310: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a s of the flag.**
6320: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
6330: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 NC_NORMAL, that
6340: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 means to use nor
6350: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 mal fsync() sema
6360: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 ntics..** If the
6370: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 lower four bits
6380: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
6390: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 NC_FULL, that me
63a0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 ans.** to use Ma
63b0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c c OS X style ful
63c0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 lsync instead of
63d0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 fsync()..**.**
63e0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 Do not confuse t
63f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e he SQLITE_SYNC_N
6400: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
6410: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 _SYNC_FULL flags
6420: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 .** with the [PR
6430: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
6440: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 ]=NORMAL and [PR
6450: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
6460: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e ]=FULL.** settin
6470: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 gs. The [synchr
6480: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 onous pragma] de
6490: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 termines when ca
64a0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 lls to the.** xS
64b0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f ync VFS method o
64c0: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 ccur and applies
64d0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 uniformly acros
64e0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e s all platforms.
64f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 .** The SQLITE_S
6500: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 YNC_NORMAL and S
6510: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
6520: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 flags determine
6530: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 how.** energetic
6540: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 or rigorous or
6550: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e forceful the syn
6560: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 c operations are
6570: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b and.** only mak
6580: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f e a difference o
6590: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 n Mac OSX for th
65a0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 e default SQLite
65b0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 code..** (Third
65c0: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 -party VFS imple
65d0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 mentations might
65e0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 also make the d
65f0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 istinction.** be
6600: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e tween SQLITE_SYN
6610: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
6620: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 ITE_SYNC_FULL, b
6630: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 ut among the.**
6640: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
6650: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f s natively suppo
6660: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 rted by SQLite,
6670: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 only Mac OSX.**
6680: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 cares about the
6690: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a difference.).*/.
66a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
66b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 YNC_NORMAL
66c0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 0x00002.#defin
66d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 e SQLITE_SYNC_FU
66e0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 LL 0x00
66f0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 003.#define SQLI
6700: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
6710: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 0x00010../
6720: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
6730: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e S Interface Open
6740: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a File Handle.**.
6750: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 ** An [sqlite3_f
6760: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 ile] object repr
6770: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 esents an open f
6780: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b ile in the .** [
6790: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 sqlite3_vfs | OS
67a0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 interface layer
67b0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f ]. Individual O
67c0: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 S interface.** i
67d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 mplementations w
67e0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 ill.** want to s
67f0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a ubclass this obj
6800: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 ect by appending
6810: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c additional fiel
6820: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 ds.** for their
6830: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d own use. The pM
6840: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 ethods entry is
6850: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
6860: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d ** [sqlite3_io_m
6870: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 ethods] object t
6880: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 hat defines meth
6890: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 ods for performi
68a0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 ng.** I/O operat
68b0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e ions on the open
68c0: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 file..*/.typede
68d0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
68e0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 _file sqlite3_fi
68f0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 le;.struct sqlit
6900: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 e3_file {. cons
6910: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 t struct sqlite3
6920: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 _io_methods *pMe
6930: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f thods; /* Metho
6940: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 ds for an open f
6950: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ile */.};../*.**
6960: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
6970: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 terface File Vir
6980: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a tual Methods Obj
6990: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 ect.**.** Every
69a0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 file opened by t
69b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
69c0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f xOpen] method po
69d0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 pulates an.** [s
69e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
69f0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f ect (or, more co
6a00: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 mmonly, a subcla
6a10: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 ss of the.** [sq
6a20: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
6a30: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 ct) with a point
6a40: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
6a50: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
6a60: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
6a70: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 defines the met
6a80: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 hods used to per
6a90: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 form various ope
6aa0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e rations.** again
6ab0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 st the open file
6ac0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
6ad0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
6ae0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a e] object..**.**
6af0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 If the [sqlite3
6b00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
6b10: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 od sets the sqli
6b20: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
6b30: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f s element .** to
6b40: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e a non-NULL poin
6b50: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 ter, then the sq
6b60: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
6b70: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a .xClose method.*
6b80: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 * may be invoked
6b90: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 even if the [sq
6ba0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
6bb0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 reported that i
6bc0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a t failed. The.*
6bd0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 * only way to pr
6be0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 event a call to
6bf0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 xClose following
6c00: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 a failed [sqlit
6c10: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a e3_vfs.xOpen].**
6c20: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c is for the [sql
6c30: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
6c40: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 to set the sqlit
6c50: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
6c60: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e element.** to N
6c70: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ULL..**.** The f
6c80: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
6c90: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e xSync may be on
6ca0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e e of [SQLITE_SYN
6cb0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 C_NORMAL] or.**
6cc0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c [SQLITE_SYNC_FUL
6cd0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 L]. The first c
6ce0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 hoice is the nor
6cf0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 mal fsync()..**
6d00: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 The second choic
6d10: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 e is a Mac OS X
6d20: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 style fullsync.
6d30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e The [SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 C_DATAONLY].** f
6d50: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 lag may be ORed
6d60: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 in to indicate t
6d70: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 hat only the dat
6d80: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a a of the file.**
6d90: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f and not its ino
6da0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 de needs to be s
6db0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ynced..**.** The
6dc0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
6dd0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 to xLock() and x
6de0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 Unlock() are one
6df0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c of.** <ul>.** <
6e00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
6e10: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 _NONE],.** <li>
6e20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 [SQLITE_LOCK_SHA
6e30: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 RED],.** <li> [S
6e40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
6e50: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 VED],.** <li> [S
6e60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
6e70: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 NG], or.** <li>
6e80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
6e90: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c LUSIVE]..** </ul
6ea0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 >.** xLock() inc
6eb0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
6ec0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 xUnlock() decre
6ed0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a ases the lock..*
6ee0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 * The xCheckRese
6ef0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f rvedLock() metho
6f00: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 d checks whether
6f10: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f any database co
6f20: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 nnection,.** eit
6f30: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 her in this proc
6f40: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f ess or in some o
6f50: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 ther process, is
6f60: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 holding a RESER
6f70: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c VED,.** PENDING,
6f80: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f or EXCLUSIVE lo
6f90: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 ck on the file.
6fa0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 It returns true
6fb0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f .** if such a lo
6fc0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 ck exists and fa
6fd0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a lse otherwise..*
6fe0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f *.** The xFileCo
6ff0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 ntrol() method i
7000: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 s a generic inte
7010: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 rface that allow
7020: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 s custom.** VFS
7030: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
7040: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 to directly cont
7050: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 rol an open file
7060: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
7070: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
7080: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 rol()] interface
7090: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f . The second "o
70a0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 p" argument is a
70b0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 n.** integer opc
70c0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 ode. The third
70d0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 argument is a ge
70e0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e neric pointer in
70f0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 tended to.** poi
7100: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 nt to a structur
7110: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 e that may conta
7120: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 in arguments or
7130: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 space in which t
7140: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 o.** write retur
7150: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e n values. Poten
7160: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 tial uses for xF
7170: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 ileControl() mig
7180: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f ht be.** functio
7190: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f ns to enable blo
71a0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 cking locks with
71b0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 timeouts, to ch
71c0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b ange the.** lock
71d0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f ing strategy (fo
71e0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 r example to use
71f0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 dot-file locks)
7200: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 , to inquire.**
7210: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 about the status
7220: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 of a lock, or t
7230: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f o break stale lo
7240: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 cks. The SQLite
7250: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 .** core reserve
7260: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 s all opcodes le
7270: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 ss than 100 for
7280: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 its own use..**
7290: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f A [SQLITE_FCNTL_
72a0: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 LOCKSTATE | list
72b0: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 of opcodes] les
72c0: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 s than 100 is av
72d0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c ailable..** Appl
72e0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 ications that de
72f0: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 fine a custom xF
7300: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
7310: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 d should use opc
7320: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 odes.** greater
7330: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 than 100 to avoi
7340: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 d conflicts. VF
7350: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
7360: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 s should.** retu
7370: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f rn [SQLITE_NOTFO
7380: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f UND] for file co
7390: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 ntrol opcodes th
73a0: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
73b0: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a * recognize..**.
73c0: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 ** The xSectorSi
73d0: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 ze() method retu
73e0: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 rns the sector s
73f0: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 ize of the.** de
7400: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c vice that underl
7410: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 ies the file. T
7420: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 he sector size i
7430: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d s the.** minimum
7440: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 write that can
7450: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 be performed wit
7460: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a hout disturbing.
7470: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 ** other bytes i
7480: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 n the file. The
7490: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
74a0: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 ristics().** met
74b0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 hod returns a bi
74c0: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 t vector describ
74d0: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 ing behaviors of
74e0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 the.** underlyi
74f0: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a ng device:.**.**
7500: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
7510: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7520: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c IC].** <li> [SQL
7530: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
7540: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 512].** <li> [SQ
7550: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7560: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C1K].** <li> [SQ
7570: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7580: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C2K].** <li> [SQ
7590: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
75a0: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C4K].** <li> [SQ
75b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
75c0: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C8K].** <li> [SQ
75d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
75e0: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C16K].** <li> [S
75f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7600: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC32K].** <li> [
7610: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7620: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC64K].** <li>
7630: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 [SQLITE_IOCAP_SA
7640: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c FE_APPEND].** <l
7650: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
7660: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 _SEQUENTIAL].**
7670: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
7680: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7690: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 MIC property mea
76a0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 ns that all writ
76b0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a es of.** any siz
76c0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 e are atomic. T
76d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
76e0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 ATOMICnnn values
76f0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 .** mean that wr
7700: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 ites of blocks t
7710: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 hat are nnn byte
7720: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a s in size and.**
7730: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 are aligned to
7740: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 an address which
7750: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d is an integer m
7760: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e ultiple of.** nn
7770: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 n are atomic. T
7780: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
7790: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 SAFE_APPEND valu
77a0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 e means.** that
77b0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 when data is app
77c0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c ended to a file,
77d0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 the data is app
77e0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 ended.** first t
77f0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 hen the size of
7800: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 the file is exte
7810: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 nded, never the
7820: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f other.** way aro
7830: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 und. The SQLITE
7840: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
7850: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 L property means
7860: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 that.** informa
7870: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 tion is written
7880: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 to disk in the s
7890: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c ame order as cal
78a0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 ls.** to xWrite(
78b0: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 )..**.** If xRea
78c0: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 d() returns SQLI
78d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
78e0: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f EAD it must also
78f0: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 fill.** in the
7900: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 unread portions
7910: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 of the buffer wi
7920: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 th zeros. A VFS
7930: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 that.** fails t
7940: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
7950: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 t reads might se
7960: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 em to work. How
7970: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 ever,.** failure
7980: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
7990: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 ort reads will e
79a0: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 ventually lead t
79b0: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f o.** database co
79c0: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 rruption..*/.typ
79d0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
79e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 te3_io_methods s
79f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7a00: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
7a10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 3_io_methods {.
7a20: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 int iVersion;.
7a30: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 int (*xClose)(s
7a40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
7a50: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 int (*xRead)(sq
7a60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 lite3_file*, voi
7a70: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
7a80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
7a90: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 t);. int (*xWri
7aa0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
7ab0: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
7ac0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
7ad0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
7ae0: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 int (*xTruncat
7af0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
7b00: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
7b10: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 size);. int (*x
7b20: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 Sync)(sqlite3_fi
7b30: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b le*, int flags);
7b40: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 . int (*xFileSi
7b50: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ze)(sqlite3_file
7b60: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
7b70: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 *pSize);. int
7b80: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 (*xLock)(sqlite3
7b90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 _file*, int);.
7ba0: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 int (*xUnlock)(s
7bb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
7bc0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 t);. int (*xChe
7bd0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 ckReservedLock)(
7be0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
7bf0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 nt *pResOut);.
7c00: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 int (*xFileContr
7c10: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ol)(sqlite3_file
7c20: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 *, int op, void
7c30: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a *pArg);. int (*
7c40: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c xSectorSize)(sql
7c50: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
7c60: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 nt (*xDeviceChar
7c70: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c acteristics)(sql
7c80: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f ite3_file*);. /
7c90: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 * Methods above
7ca0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 are valid for ve
7cb0: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 rsion 1 */. int
7cc0: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 (*xShmMap)(sqli
7cd0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 te3_file*, int i
7ce0: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e Pg, int pgsz, in
7cf0: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 t, void volatile
7d00: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 **);. int (*xSh
7d10: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 mLock)(sqlite3_f
7d20: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 ile*, int offset
7d30: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 , int n, int fla
7d40: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 gs);. void (*xS
7d50: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 hmBarrier)(sqlit
7d60: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
7d70: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 (*xShmUnmap)(sq
7d80: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
7d90: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 deleteFlag);.
7da0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
7db0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
7dc0: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a ersion 2 */. /*
7dd0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 Additional meth
7de0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ods may be added
7df0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
7e00: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ses */.};../*.**
7e10: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 CAPI3REF: Stand
7e20: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c ard File Control
7e30: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 Opcodes.**.** T
7e40: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e hese integer con
7e50: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 stants are opcod
7e60: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 es for the xFile
7e70: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a Control method.*
7e80: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
7e90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
7ea0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 ject and for the
7eb0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
7ec0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 ontrol()].** int
7ed0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 erface..**.** Th
7ee0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
7ef0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 LOCKSTATE] opcod
7f00: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
7f10: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
7f20: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
7f30: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
7f40: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 method to write
7f50: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
7f60: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 te of.** the loc
7f70: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 k (one of [SQLIT
7f80: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 E_LOCK_NONE], [S
7f90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
7fa0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c D],.** [SQLITE_L
7fb0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b OCK_RESERVED], [
7fc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
7fd0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ING], or [SQLITE
7fe0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d _LOCK_EXCLUSIVE]
7ff0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 ).** into an int
8000: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 eger that the pA
8010: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e rg argument poin
8020: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 ts to. This capa
8030: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 bility.** is use
8040: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 d during testing
8050: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 and only needs
8060: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 to be supported
8070: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 when SQLITE_TEST
8080: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a .** is defined..
8090: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b ** <ul>.** <li>[
80a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 [SQLITE_FCNTL_SI
80b0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 ZE_HINT]].** The
80c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 [SQLITE_FCNTL_S
80d0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 IZE_HINT] opcode
80e0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 is used by SQLi
80f0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 te to give the V
8100: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 FS.** layer a hi
8110: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 nt of how large
8120: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
8130: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 e will grow to b
8140: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 e during the.**
8150: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 current transact
8160: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 ion. This hint
8170: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 is not guarantee
8180: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 d to be accurate
8190: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 but it.** is of
81a0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 ten close. The
81b0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d underlying VFS m
81c0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 ight choose to p
81d0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 reallocate datab
81e0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 ase.** file spac
81f0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 e based on this
8200: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f hint in order to
8210: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 help writes to
8220: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
8230: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e file run faster.
8240: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
8250: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
8260: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 SIZE]].** The [S
8270: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e QLITE_FCNTL_CHUN
8280: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 K_SIZE] opcode i
8290: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 s used to reques
82a0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a t that the VFS.*
82b0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 * extends and tr
82c0: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 uncates the data
82d0: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 base file in chu
82e0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 nks of a size sp
82f0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 ecified.** by th
8300: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 e user. The four
8310: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b th argument to [
8320: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
8330: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a trol()] should .
8340: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 ** point to an i
8350: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 nteger (type int
8360: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 ) containing the
8370: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 new chunk-size
8380: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 to use.** for th
8390: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 e nominated data
83a0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 base. Allocating
83b0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 database file s
83c0: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a pace in large.**
83d0: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 chunks (say 1MB
83e0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 at a time), may
83f0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 reduce file-sys
8400: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f tem fragmentatio
8410: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 n and.** improve
8420: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 performance on
8430: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a some systems..**
8440: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
8450: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e _FCNTL_FILE_POIN
8460: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 TER]].** The [SQ
8470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f LITE_FCNTL_FILE_
8480: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 POINTER] opcode
8490: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 is used to obtai
84a0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 n a pointer.** t
84b0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 o the [sqlite3_f
84c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f ile] object asso
84d0: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 ciated with a pa
84e0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 rticular databas
84f0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
8500: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 See the [sqlit
8510: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
8520: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e )] documentation
8530: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e for.** addition
8540: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
8550: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
8560: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d TE_FCNTL_SYNC_OM
8570: 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 ITTED]].** ^(The
8580: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 [SQLITE_FCNTL_S
8590: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 YNC_OMITTED] opc
85a0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 ode is generated
85b0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a internally by.*
85c0: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e * SQLite and sen
85d0: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 t to all VFSes i
85e0: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c n place of a cal
85f0: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d l to the xSync m
8600: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 ethod.** when th
8610: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
8620: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d ction has [PRAGM
8630: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 A synchronous] s
8640: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 et to OFF.)^.**
8650: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 Some specialized
8660: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 VFSes need this
8670: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 signal in order
8680: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 to operate corr
8690: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 ectly.** when [P
86a0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
86b0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 s | PRAGMA synch
86c0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 ronous=OFF] is s
86d0: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a et, but most .**
86e0: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 VFSes do not ne
86f0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 ed this signal a
8700: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 nd should silent
8710: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f ly ignore this o
8720: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 pcode..** Applic
8730: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f ations should no
8740: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f t call [sqlite3_
8750: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
8760: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 with this.** opc
8770: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 ode as doing so
8780: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 may disrupt the
8790: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 operation of the
87a0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 specialized VFS
87b0: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 es.** that do re
87c0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a quire it. .**.*
87d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
87e0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
87f0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 TRY]].** ^The [S
8800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
8810: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 2_AV_RETRY] opco
8820: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f de is used to co
8830: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 nfigure automati
8840: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 c.** retry count
8850: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 s and intervals
8860: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b for certain disk
8870: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 I/O operations
8880: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f for the.** windo
8890: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 ws [VFS] in orde
88a0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 r to provide rob
88b0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 ustness in the p
88c0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e resence of.** an
88d0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d ti-virus program
88e0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 s. By default,
88f0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 the windows VFS
8900: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 will retry file
8910: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 read,.** file wr
8920: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 ite, and file de
8930: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 lete operations
8940: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 up to 10 times,
8950: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 with a delay.**
8960: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e of 25 millisecon
8970: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 ds before the fi
8980: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 rst retry and wi
8990: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 th the delay inc
89a0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e reasing.** by an
89b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d additional 25 m
89c0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 illiseconds with
89d0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 each subsequent
89e0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a retry. This.**
89f0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 opcode allows t
8a00: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 hese two values
8a10: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 (10 retries and
8a20: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 25 milliseconds
8a30: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 of delay).** to
8a40: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 be adjusted. Th
8a50: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 e values are cha
8a60: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 nged for all dat
8a70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
8a80: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 s.** within the
8a90: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 same process. T
8aa0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
8ab0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 pointer to an a
8ac0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 rray of two.** i
8ad0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 ntegers where th
8ae0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 e first integer
8af0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 i the new retry
8b00: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 count and the se
8b10: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 cond.** integer
8b20: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 is the delay. I
8b30: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 f either integer
8b40: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
8b50: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a en the setting.*
8b60: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
8b70: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 but instead the
8b80: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
8b90: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 that setting is
8ba0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 written.** into
8bb0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c the array entry,
8bc0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 allowing the cu
8bd0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 rrent retry sett
8be0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e ings to be.** in
8bf0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 terrogated. The
8c00: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 zDbName paramet
8c10: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a er is ignored..*
8c20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
8c30: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
8c40: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 WAL]].** ^The [S
8c50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
8c60: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 IST_WAL] opcode
8c70: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f is used to set o
8c80: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 r query the.** p
8c90: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c ersistent [WAL |
8ca0: 20 57 72 69 74 65 20 41 48 65 61 64 20 4c 6f 67 Write AHead Log
8cb0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 ] setting. By d
8cc0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 efault, the auxi
8cd0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 liary.** write a
8ce0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 head log and sha
8cf0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 red memory files
8d00: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 used for transa
8d10: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a ction control.**
8d20: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c are automatical
8d30: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ly deleted when
8d40: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 the latest conne
8d50: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 ction to the dat
8d60: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e abase.** closes.
8d70: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 Setting persis
8d80: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 tent WAL mode ca
8d90: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 uses those files
8da0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 to persist afte
8db0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 r.** close. Per
8dc0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 sisting the file
8dd0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e s is useful when
8de0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 other processes
8df0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 that do not.**
8e00: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 have write permi
8e10: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 ssion on the dir
8e20: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e ectory containin
8e30: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 g the database f
8e40: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 ile want.** to r
8e50: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 ead the database
8e60: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 file, as the WA
8e70: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d L and shared mem
8e80: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 ory files must e
8e90: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 xist.** in order
8ea0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 for the databas
8eb0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 e to be readable
8ec0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 . The fourth pa
8ed0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
8ee0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
8ef0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 rol()] for this
8f00: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 opcode should be
8f10: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
8f20: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 integer..** Tha
8f30: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 t integer is 0 t
8f40: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 o disable persis
8f50: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 tent WAL mode or
8f60: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 1 to enable per
8f70: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d sistent.** WAL m
8f80: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
8f90: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
8fa0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
8fb0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
8fc0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 ent.** WAL persi
8fd0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a stence setting..
8fe0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
8ff0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
9000: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a FE_OVERWRITE]].*
9010: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
9020: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f CNTL_POWERSAFE_O
9030: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 VERWRITE] opcode
9040: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 is used to set
9050: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 or query the.**
9060: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 persistent "powe
9070: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 rsafe-overwrite"
9080: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 or "PSOW" setti
9090: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 ng. The PSOW se
90a0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 tting.** determi
90b0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f nes the [SQLITE_
90c0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
90d0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f OVERWRITE] bit o
90e0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 f the.** xDevice
90f0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
9100: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 methods. The fou
9110: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
9120: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
9130: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 e_control()] for
9140: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f this opcode sho
9150: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 uld be a pointer
9160: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a to an integer..
9170: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 ** That integer
9180: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
9190: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
91a0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 or 1 to enable
91b0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d zero-damage.** m
91c0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
91d0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
91e0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
91f0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
9200: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 ent.** zero-dama
9210: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e ge mode setting.
9220: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
9230: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 ITE_FCNTL_OVERWR
9240: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 ITE]].** ^The [S
9250: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
9260: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 WRITE] opcode is
9270: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 invoked by SQLi
9280: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 te after opening
9290: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e .** a write tran
92a0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 saction to indic
92b0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 ate that, unless
92c0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 it is rolled ba
92d0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 ck for some.** r
92e0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 eason, the entir
92f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
9300: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 will be overwrit
9310: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 ten by the curre
9320: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 nt .** transacti
9330: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 on. This is used
9340: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 by VACUUM opera
9350: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tions..**.** <li
9360: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
9370: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 VFSNAME]].** ^Th
9380: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
9390: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 VFSNAME] opcode
93a0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
93b0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 btain the names
93c0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 of.** all [VFSes
93d0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 ] in the VFS sta
93e0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 ck. The names a
93f0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 re of all VFS sh
9400: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 ims and the.** f
9410: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 inal bottom-leve
9420: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 l VFS are writte
9430: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
9440: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 tained from .**
9450: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
9460: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c )] and the resul
9470: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 t is stored in t
9480: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c he char* variabl
9490: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f e.** that the fo
94a0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f urth parameter o
94b0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f f [sqlite3_file_
94c0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 control()] point
94d0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c s to..** The cal
94e0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ler is responsib
94f0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 le for freeing t
9500: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 he memory when d
9510: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a one. As with.**
9520: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f all file-contro
9530: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 l actions, there
9540: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 is no guarantee
9550: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 that this will
9560: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 actually.** do a
9570: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 nything. Caller
9580: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c s should initial
9590: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 ize the char* va
95a0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c riable to a NULL
95b0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 .** pointer in c
95c0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f ase this file-co
95d0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 ntrol is not imp
95e0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 lemented. This
95f0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 file-control.**
9600: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 is intended for
9610: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f diagnostic use o
9620: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nly..**.** <li>[
9630: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
9640: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 AGMA]].** ^Whene
9650: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 ver a [PRAGMA] s
9660: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 tatement is pars
9670: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 ed, an [SQLITE_F
9680: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a CNTL_PRAGMA] .**
9690: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 file control is
96a0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 sent to the ope
96b0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d n [sqlite3_file]
96c0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f object correspo
96d0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 nding.** to the
96e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f database file to
96f0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d which the pragm
9700: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 a statement refe
9710: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e rs. ^The argumen
9720: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c t.** to the [SQL
9730: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
9740: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
9750: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a s an array of.**
9760: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
9770: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e ings (char**) in
9780: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e which the secon
9790: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 d element of the
97a0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 array.** is the
97b0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 name of the pra
97c0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 gma and the thir
97d0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 d element is the
97e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
97f0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 .** pragma or NU
9800: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 LL if the pragma
9810: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 has no argument
9820: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 . ^The handler
9830: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 for an.** [SQLIT
9840: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
9850: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e file control can
9860: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 optionally make
9870: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 the first eleme
9880: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 nt.** of the cha
9890: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 r** argument poi
98a0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f nt to a string o
98b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
98c0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
98d0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 .** or the equiv
98e0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 alent and that s
98f0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d tring will becom
9900: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 e the result of
9910: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a the pragma or.**
9920: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
9930: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 ge if the pragma
9940: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a fails. ^If the.
9950: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
9960: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
9970: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
9980: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
9990: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a then normal .**
99a0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 [PRAGMA] proces
99b0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 sing continues.
99c0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
99d0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a _FCNTL_PRAGMA].*
99e0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 * file control r
99f0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
9a00: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 K], then the par
9a10: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 ser assumes that
9a20: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 the.** VFS has
9a30: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 handled the PRAG
9a40: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 MA itself and th
9a50: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 e parser generat
9a60: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 es a no-op.** pr
9a70: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
9a80: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 . ^If the [SQLI
9a90: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
9aa0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 file control re
9ab0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 turns.** any res
9ac0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 ult code other t
9ad0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 han [SQLITE_OK]
9ae0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f or [SQLITE_NOTFO
9af0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 UND], that means
9b00: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 .** that the VFS
9b10: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 encountered an
9b20: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 error while hand
9b30: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 ling the [PRAGMA
9b40: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d ] and the.** com
9b50: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 pilation of the
9b60: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 PRAGMA fails wit
9b70: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 h an error. ^Th
9b80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
9b90: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 PRAGMA].** file
9ba0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 control occurs a
9bb0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 t the beginning
9bc0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d of pragma statem
9bd0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 ent analysis and
9be0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c so.** it is abl
9bf0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 e to override bu
9c00: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 ilt-in [PRAGMA]
9c10: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c statements..** <
9c20: 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /ul>.*/.#define
9c30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
9c40: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 KSTATE
9c50: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
9c60: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 QLITE_GET_LOCKPR
9c70: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 OXYFILE
9c80: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
9c90: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f LITE_SET_LOCKPRO
9ca0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 XYFILE
9cb0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
9cc0: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 ITE_LAST_ERRNO
9cd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
9ce0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
9cf0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 TE_FCNTL_SIZE_HI
9d00: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 NT
9d10: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 5.#define SQLIT
9d20: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
9d30: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
9d40: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
9d50: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e _FCNTL_FILE_POIN
9d60: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 TER 7
9d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9d80: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 FCNTL_SYNC_OMITT
9d90: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a ED 8.
9da0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
9db0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
9dc0: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 TRY 9.#
9dd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
9de0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 NTL_PERSIST_WAL
9df0: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 10.#d
9e00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
9e10: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 TL_OVERWRITE
9e20: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 11.#de
9e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
9e40: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 L_VFSNAME
9e50: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 12.#def
9e60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
9e70: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
9e80: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 RITE 13.#defi
9e90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
9ea0: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 PRAGMA
9eb0: 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 14../*.**
9ec0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
9ed0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 Handle.**.** Th
9ee0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 e mutex module w
9ef0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 ithin SQLite def
9f00: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 ines [sqlite3_mu
9f10: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a tex] to be an.**
9f20: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 abstract type f
9f30: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 or a mutex objec
9f40: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 t. The SQLite c
9f50: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a ore never looks.
9f60: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e ** at the intern
9f70: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
9f80: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 n of an [sqlite3
9f90: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c _mutex]. It onl
9fa0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 y.** deals with
9fb0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 pointers to the
9fc0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
9fd0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 object..**.** Mu
9fe0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 texes are create
9ff0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
a000: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e _mutex_alloc()].
a010: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
a020: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
a030: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a sqlite3_mutex;.
a040: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
a050: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 OS Interface Ob
a060: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e ject.**.** An in
a070: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 stance of the sq
a080: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 lite3_vfs object
a090: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
a0a0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a erface between.*
a0b0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 * the SQLite cor
a0c0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c e and the underl
a0d0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 ying operating s
a0e0: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 ystem. The "vfs
a0f0: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 ".** in the name
a100: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 of the object s
a110: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 tands for "virtu
a120: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e al file system".
a130: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 See.** the [VF
a140: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 S | VFS document
a150: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 ation] for furth
a160: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a er information..
a170: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 **.** The value
a180: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 of the iVersion
a190: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c field is initial
a1a0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 ly 1 but may be
a1b0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 larger in.** fut
a1c0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
a1d0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f SQLite. Additio
a1e0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 nal fields may b
a1f0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 e appended to th
a200: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 is.** object whe
a210: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 n the iVersion v
a220: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 alue is increase
a230: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 d. Note that th
a240: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f e structure.** o
a250: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
a260: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 s object changes
a270: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 in the transact
a280: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 ion between.** S
a290: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
a2a0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 5.9 and 3.6.0 an
a2b0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 d yet the iVersi
a2c0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 on field was not
a2d0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a .** modified..**
a2e0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 .** The szOsFile
a2f0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 field is the si
a300: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 ze of the subcla
a310: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 ssed [sqlite3_fi
a320: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 le].** structure
a330: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 used by this VF
a340: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 S. mxPathname i
a350: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 s the maximum le
a360: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 ngth of.** a pat
a370: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 hname in this VF
a380: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 S..**.** Registe
a390: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 red sqlite3_vfs
a3a0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 objects are kept
a3b0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 on a linked lis
a3c0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 t formed by.** t
a3d0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
a3e0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
a3f0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a vfs_register()].
a400: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
a410: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 vfs_unregister()
a420: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e ] interfaces man
a430: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a age this list.**
a440: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 in a thread-saf
a450: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c e way. The [sql
a460: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d ite3_vfs_find()]
a470: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 interface.** se
a480: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e arches the list.
a490: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 Neither the ap
a4a0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e plication code n
a4b0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d or the VFS.** im
a4c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f plementation sho
a4d0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 uld use the pNex
a4e0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a t pointer..**.**
a4f0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 The pNext field
a500: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 is the only fie
a510: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ld in the sqlite
a520: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 3_vfs.** structu
a530: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 re that SQLite w
a540: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e ill ever modify.
a550: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e SQLite will on
a560: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 ly access.** or
a570: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c modify this fiel
a580: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 d while holding
a590: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 a particular sta
a5a0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 tic mutex..** Th
a5b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
a5c0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 ould never modif
a5d0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 y anything withi
a5e0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
a5f0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 s.** object once
a600: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 the object has
a610: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e been registered.
a620: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 .**.** The zName
a630: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 field holds the
a640: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 name of the VFS
a650: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 module. The na
a660: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e me must.** be un
a670: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 ique across all
a680: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a VFS modules..**.
a690: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 ** [[sqlite3_vfs
a6a0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c .xOpen]].** ^SQL
a6b0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 ite guarantees t
a6c0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d hat the zFilenam
a6d0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 e parameter to x
a6e0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 Open.** is eithe
a6f0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
a700: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 or string obtai
a710: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c ned.** from xFul
a720: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 lPathname() with
a730: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 an optional suf
a740: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 fix added..** ^I
a750: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 f a suffix is ad
a760: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 ded to the zFile
a770: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 name parameter,
a780: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 it will.** consi
a790: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 st of a single "
a7a0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c -" character fol
a7b0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 lowed by no more
a7c0: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 than.** 11 alph
a7d0: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 anumeric and/or
a7e0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a "-" characters..
a7f0: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 ** ^SQLite furth
a800: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 er guarantees th
a810: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 at.** the string
a820: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 will be valid a
a830: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 nd unchanged unt
a840: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a il xClose() is.*
a850: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 * called. Becaus
a860: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 e of the previou
a870: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 s sentence,.** t
a880: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
a890: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f ] can safely sto
a8a0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 re a pointer to
a8b0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 the.** filename
a8c0: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 if it needs to r
a8d0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 emember the file
a8e0: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 name for some re
a8f0: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ason..** If the
a900: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 zFilename parame
a910: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 ter to xOpen is
a920: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
a930: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 hen xOpen.** mus
a940: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e t invent its own
a950: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 temporary name
a960: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e for the file. ^
a970: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a Whenever the .**
a980: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d xFilename param
a990: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 eter is NULL it
a9a0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 will also be the
a9b0: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a case that the.*
a9c0: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 * flags paramete
a9d0: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b r will include [
a9e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
a9f0: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a TEONCLOSE]..**.*
aa00: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 * The flags argu
aa10: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 ment to xOpen()
aa20: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 includes all bit
aa30: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 s set in.** the
aa40: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
aa50: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f o [sqlite3_open_
aa60: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 v2()]. Or if [s
aa70: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a qlite3_open()].*
aa80: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 * or [sqlite3_op
aa90: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c en16()] is used,
aaa0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c then flags incl
aab0: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a udes at least.**
aac0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
aad0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 ADWRITE] | [SQLI
aae0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e TE_OPEN_CREATE].
aaf0: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 .** If xOpen()
ab00: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 opens a file rea
ab10: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 d-only then it s
ab20: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 ets *pOutFlags t
ab30: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 o.** include [SQ
ab40: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
ab50: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 LY]. Other bits
ab60: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d in *pOutFlags m
ab70: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a ay be set..**.**
ab80: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 ^(SQLite will a
ab90: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
aba0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
abb0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 gs to the xOpen(
abc0: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e ).** call, depen
abd0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 ding on the obje
abe0: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a ct being opened:
abf0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
ac00: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
ac10: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c N_MAIN_DB].** <l
ac20: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
ac30: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a _MAIN_JOURNAL].*
ac40: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
ac50: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a OPEN_TEMP_DB].**
ac60: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
ac70: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c PEN_TEMP_JOURNAL
ac80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
ac90: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e TE_OPEN_TRANSIEN
aca0: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b T_DB].** <li> [
acb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a SQLITE_OPEN_SUBJ
acc0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
acd0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
ace0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a STER_JOURNAL].**
acf0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
ad00: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c PEN_WAL].** </ul
ad10: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 >)^.**.** The fi
ad20: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 le I/O implement
ad30: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 ation can use th
ad40: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c e object type fl
ad50: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 ags to.** change
ad60: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c the way it deal
ad70: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 s with files. F
ad80: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 or example, an a
ad90: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 pplication.** th
ada0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 at does not care
adb0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 about crash rec
adc0: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 overy or rollbac
add0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 k might make.**
ade0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f the open of a jo
adf0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d urnal file a no-
ae00: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 op. Writes to t
ae10: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c his journal woul
ae20: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d d.** also be no-
ae30: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 ops, and any att
ae40: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 empt to read the
ae50: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 journal would r
ae60: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f eturn.** SQLITE_
ae70: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 IOERR. Or the i
ae80: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 mplementation mi
ae90: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 ght recognize th
aea0: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a at a database.**
aeb0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f file will be do
aec0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 ing page-aligned
aed0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e sector reads an
aee0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 d writes in a ra
aef0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e ndom.** order an
af00: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f d set up its I/O
af10: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 subsystem accor
af20: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 dingly..**.** SQ
af30: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 Lite might also
af40: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 add one of the f
af50: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 ollowing flags t
af60: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 o the xOpen meth
af70: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a od:.**.** <ul>.*
af80: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f * <li> [SQLITE_O
af90: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
afa0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 E].** <li> [SQLI
afb0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
afc0: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a E].** </ul>.**.*
afd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 * The [SQLITE_OP
afe0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
aff0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 ] flag means the
b000: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a file should be.
b010: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ** deleted when
b020: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e it is closed. ^
b030: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
b040: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a _DELETEONCLOSE].
b050: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 ** will be set f
b060: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 or TEMP database
b070: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 s and their jour
b080: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a nals, transient.
b090: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e ** databases, an
b0a0: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a d subjournals..*
b0b0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 *.** ^The [SQLIT
b0c0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
b0d0: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 ] flag is always
b0e0: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 used in conjunc
b0f0: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 tion.** with the
b100: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
b110: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 EATE] flag, whic
b120: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 h are both direc
b130: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 tly.** analogous
b140: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 to the O_EXCL a
b150: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 nd O_CREAT flags
b160: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 of the POSIX op
b170: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 en().** API. Th
b180: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 e SQLITE_OPEN_EX
b190: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 CLUSIVE flag, wh
b1a0: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 en paired with t
b1b0: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 he .** SQLITE_OP
b1c0: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 EN_CREATE, is us
b1d0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
b1e0: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 hat file should
b1f0: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 always.** be cre
b200: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 ated, and that i
b210: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 t is an error if
b220: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 it already exis
b230: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e ts..** It is <i>
b240: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 not</i> used to
b250: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c indicate the fil
b260: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e e should be open
b270: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 ed .** for exclu
b280: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a sive access..**.
b290: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f ** ^At least szO
b2a0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d sFile bytes of m
b2b0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 emory are alloca
b2c0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a ted by SQLite.**
b2d0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 to hold the [s
b2e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 qlite3_file] str
b2f0: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 ucture passed as
b300: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 the third.** ar
b310: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e gument to xOpen.
b320: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 The xOpen meth
b330: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 od does not have
b340: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 to.** allocate
b350: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 the structure; i
b360: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 t should just fi
b370: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 ll it in. Note
b380: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 that.** the xOpe
b390: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 n method must se
b3a0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
b3b0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 le.pMethods to e
b3c0: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 ither.** a valid
b3d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
b3e0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 hods] object or
b3f0: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 to NULL. xOpen
b400: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 must do.** this
b410: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e even if the open
b420: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 fails. SQLite
b430: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 expects that the
b440: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
b450: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e ethods.** elemen
b460: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 t will be valid
b470: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 after xOpen retu
b480: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f rns regardless o
b490: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a f the success.**
b4a0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 or failure of t
b4b0: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a he xOpen call..*
b4c0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 *.** [[sqlite3_v
b4d0: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 fs.xAccess]].**
b4e0: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d ^The flags argum
b4f0: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 ent to xAccess()
b500: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f may be [SQLITE_
b510: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a ACCESS_EXISTS].*
b520: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 * to test for th
b530: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 e existence of a
b540: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 file, or [SQLIT
b550: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
b560: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 TE] to.** test w
b570: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 hether a file is
b580: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 readable and wr
b590: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 itable, or [SQLI
b5a0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a TE_ACCESS_READ].
b5b0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 ** to test wheth
b5c0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 er a file is at
b5d0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 least readable.
b5e0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 The file can b
b5f0: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 e a.** directory
b600: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ..**.** ^SQLite
b610: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f will always allo
b620: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 cate at least mx
b630: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 Pathname+1 bytes
b640: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 for the.** outp
b650: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 ut buffer xFullP
b660: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 athname. The ex
b670: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 act size of the
b680: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
b690: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 is also passed
b6a0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 as a parameter t
b6b0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e o both methods.
b6c0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 If the output b
b6d0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 uffer.** is not
b6e0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 large enough, [S
b6f0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
b700: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e should be return
b710: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 ed. Since this i
b720: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 s.** handled as
b730: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 a fatal error by
b740: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 SQLite, vfs imp
b750: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
b760: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 uld endeavor.**
b770: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 to prevent this
b780: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 by setting mxPat
b790: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 hname to a suffi
b7a0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 ciently large va
b7b0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 lue..**.** The x
b7c0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 Randomness(), xS
b7d0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 leep(), xCurrent
b7e0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 Time(), and xCur
b7f0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a rentTimeInt64().
b800: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 ** interfaces ar
b810: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 e not strictly a
b820: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c part of the fil
b830: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 esystem, but the
b840: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 y are.** include
b850: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 d in the VFS str
b860: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c ucture for compl
b870: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 eteness..** The
b880: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 xRandomness() fu
b890: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 nction attempts
b8a0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 to return nBytes
b8b0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f bytes.** of goo
b8c0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d d-quality random
b8d0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 ness into zOut.
b8e0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 The return valu
b8f0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 e is.** the actu
b900: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 al number of byt
b910: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 es of randomness
b920: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 obtained..** Th
b930: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f e xSleep() metho
b940: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c d causes the cal
b950: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 ling thread to s
b960: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c leep for at.** l
b970: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 east the number
b980: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 of microseconds
b990: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 given. ^The xCu
b9a0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d rrentTime().** m
b9b0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
b9c0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 Julian Day Numbe
b9d0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e r for the curren
b9e0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 t date and time
b9f0: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 as.** a floating
ba00: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a point value..**
ba10: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 ^The xCurrentTi
ba20: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 meInt64() method
ba30: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 returns, as an
ba40: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c integer, the Jul
ba50: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 ian.** Day Numbe
ba60: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 r multiplied by
ba70: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 86400000 (the nu
ba80: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
ba90: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 onds in .** a 24
baa0: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a -hour day). .**
bab0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
bac0: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 e the xCurrentTi
bad0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 meInt64() method
bae0: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 to get the curr
baf0: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 ent.** date and
bb00: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 time if that met
bb10: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 hod is available
bb20: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 (if iVersion is
bb30: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 2 or .** greate
bb40: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 r and the functi
bb50: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f on pointer is no
bb60: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c t NULL) and will
bb70: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f fall back.** to
bb80: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 xCurrentTime()
bb90: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 if xCurrentTimeI
bba0: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 nt64() is unavai
bbb0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 lable..**.** ^Th
bbc0: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c e xSetSystemCall
bbd0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 (), xGetSystemCa
bbe0: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 ll(), and xNestS
bbf0: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 ystemCall() inte
bc00: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f rfaces.** are no
bc10: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 t used by the SQ
bc20: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 Lite core. Thes
bc30: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 e optional inter
bc40: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 faces are provid
bc50: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 ed.** by some VF
bc60: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 Ses to facilitat
bc70: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 e testing of the
bc80: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 VFS code. By ov
bc90: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 erriding .** sys
bca0: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 tem calls with f
bcb0: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 unctions under i
bcc0: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 ts control, a te
bcd0: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a st program can.*
bce0: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 * simulate fault
bcf0: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 s and error cond
bd00: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c itions that woul
bd10: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 d otherwise be d
bd20: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 ifficult.** or i
bd30: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 mpossible to ind
bd40: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 uce. The set of
bd50: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 system calls th
bd60: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 at can be overri
bd70: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 dden.** varies f
bd80: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 rom one VFS to a
bd90: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d nother, and from
bda0: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 one version of
bdb0: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 the same VFS to
bdc0: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 the.** next. Ap
bdd0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
bde0: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 use these interf
bdf0: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 aces must be pre
be00: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a pared for any.**
be10: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 or all of these
be20: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 interfaces to b
be30: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 e NULL or for th
be40: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 eir behavior to
be50: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f change.** from o
be60: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 ne release to th
be70: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 e next. Applica
be80: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 tions must not a
be90: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 ttempt to access
bea0: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 .** any of these
beb0: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 methods if the
bec0: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 iVersion of the
bed0: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e VFS is less than
bee0: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 3..*/.typedef s
bef0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
bf00: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 s sqlite3_vfs;.t
bf10: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 ypedef void (*sq
bf20: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 lite3_syscall_pt
bf30: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 r)(void);.struct
bf40: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 sqlite3_vfs {.
bf50: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 int iVersion;
bf60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 /* Str
bf70: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e ucture version n
bf80: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 umber (currently
bf90: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 3) */. int szO
bfa0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 sFile;
bfb0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 /* Size of sub
bfc0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f classed sqlite3_
bfd0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 file */. int mx
bfe0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 Pathname;
bff0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 /* Maximum fi
c000: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 le pathname leng
c010: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f th */. sqlite3_
c020: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 vfs *pNext;
c030: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 /* Next registe
c040: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e red VFS */. con
c050: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 st char *zName;
c060: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
c070: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 this virtual fi
c080: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 le system */. v
c090: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 oid *pAppData;
c0a0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 /* Point
c0b0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f er to applicatio
c0c0: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 n-specific data
c0d0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e */. int (*xOpen
c0e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
c0f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
c100: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e, sqlite3_file*
c110: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
c120: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 int flags, int
c130: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 *pOutFlags);. i
c140: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 nt (*xDelete)(sq
c150: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
c160: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
c170: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 nt syncDir);. i
c180: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 nt (*xAccess)(sq
c190: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
c1a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
c1b0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 nt flags, int *p
c1c0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
c1d0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 *xFullPathname)(
c1e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
c1f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
c200: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 int nOut, char
c210: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a *zOut);. void *
c220: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 (*xDlOpen)(sqlit
c230: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
c240: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b har *zFilename);
c250: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 . void (*xDlErr
c260: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a or)(sqlite3_vfs*
c270: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 , int nByte, cha
c280: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 r *zErrMsg);. v
c290: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 oid (*(*xDlSym)(
c2a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 sqlite3_vfs*,voi
c2b0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a d*, const char *
c2c0: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b zSymbol))(void);
c2d0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f . void (*xDlClo
c2e0: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a se)(sqlite3_vfs*
c2f0: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 , void*);. int
c300: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 (*xRandomness)(s
c310: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
c320: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f nByte, char *zO
c330: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c ut);. int (*xSl
c340: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 eep)(sqlite3_vfs
c350: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f *, int microseco
c360: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 nds);. int (*xC
c370: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 urrentTime)(sqli
c380: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 te3_vfs*, double
c390: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 *);. int (*xGet
c3a0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 LastError)(sqlit
c3b0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 e3_vfs*, int, ch
c3c0: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a ar *);. /*. **
c3d0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
c3e0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
c3f0: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 n 1 of the sqlit
c400: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a e_vfs object. *
c410: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 * definition. T
c420: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 hose that follow
c430: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 are added in ve
c440: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 rsion 2 or later
c450: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 . */. int (*xC
c460: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 urrentTimeInt64)
c470: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 (sqlite3_vfs*, s
c480: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a qlite3_int64*);.
c490: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 /*. ** The me
c4a0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
c4b0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e in versions 1 an
c4c0: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 d 2 of the sqlit
c4d0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 e_vfs object..
c4e0: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 ** Those below a
c4f0: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 re for version 3
c500: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 and greater..
c510: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 */. int (*xSetS
c520: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 ystemCall)(sqlit
c530: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
c540: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 har *zName, sqli
c550: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 te3_syscall_ptr)
c560: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 ;. sqlite3_sysc
c570: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 all_ptr (*xGetSy
c580: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
c590: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
c5a0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f ar *zName);. co
c5b0: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 nst char *(*xNex
c5c0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c tSystemCall)(sql
c5d0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
c5e0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 char *zName);.
c5f0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
c600: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
c610: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 n versions 1 thr
c620: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 ough 3 of the sq
c630: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e lite_vfs object.
c640: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 . ** New fields
c650: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
c660: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 in figure versi
c670: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 ons. The iVersi
c680: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 on. ** value wi
c690: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 ll increment whe
c6a0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 never this happe
c6b0: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a ns. . */.};../*
c6c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c .** CAPI3REF: Fl
c6d0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 ags for the xAcc
c6e0: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a ess VFS method.*
c6f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
c700: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e er constants can
c710: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 be used as the
c720: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
c730: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 to.** the xAcces
c740: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b s method of an [
c750: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
c760: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 ect. They deter
c770: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e mine.** what kin
c780: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 d of permissions
c790: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
c7a0: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 hod is looking f
c7b0: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 or..** With SQLI
c7c0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 TE_ACCESS_EXISTS
c7d0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 , the xAccess me
c7e0: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 thod.** simply c
c7f0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 hecks whether th
c800: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a e file exists..*
c810: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 * With SQLITE_AC
c820: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 CESS_READWRITE,
c830: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
c840: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 od.** checks whe
c850: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 ther the named d
c860: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 irectory is both
c870: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 readable and wr
c880: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 itable.** (in ot
c890: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 her words, if fi
c8a0: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 les can be added
c8b0: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 , removed, and r
c8c0: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a enamed within.**
c8d0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e the directory).
c8e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 .** The SQLITE_A
c8f0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 CCESS_READWRITE
c900: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 constant is curr
c910: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 ently used only
c920: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f by the.** [temp_
c930: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
c940: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 pragma], though
c950: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 this could chang
c960: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a e in a future.**
c970: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
c980: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 te..** With SQLI
c990: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 TE_ACCESS_READ,
c9a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
c9b0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 od.** checks whe
c9c0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 ther the file is
c9d0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 readable. The
c9e0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
c9f0: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a AD constant is.*
ca00: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 * currently unus
ca10: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 ed, though it mi
ca20: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 ght be used in a
ca30: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
ca40: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f of.** SQLite..*/
ca50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ca60: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 ACCESS_EXISTS
ca70: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
ca80: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
ca90: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 TE 1 /* Used b
caa0: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 y PRAGMA temp_st
cab0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f ore_directory */
cac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
cad0: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 ACCESS_READ
cae0: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2 /* Unused *
caf0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
cb00: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 F: Flags for the
cb10: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 xShmLock VFS me
cb20: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 thod.**.** These
cb30: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
cb40: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 ts define the va
cb50: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 rious locking op
cb60: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f erations.** allo
cb70: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c wed by the xShmL
cb80: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 ock method of [s
cb90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
cba0: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c s]. The.** foll
cbb0: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e owing are the on
cbc0: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 ly legal combina
cbd0: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 tions of flags t
cbe0: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 o the.** xShmLoc
cbf0: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 k method:.**.**
cc00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 <ul>.** <li> SQ
cc10: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 LITE_SHM_LOCK |
cc20: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 SQLITE_SHM_SHARE
cc30: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 D.** <li> SQLIT
cc40: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c E_SHM_LOCK | SQL
cc50: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
cc60: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 E.** <li> SQLIT
cc70: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 E_SHM_UNLOCK | S
cc80: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
cc90: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
cca0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 _SHM_UNLOCK | SQ
ccb0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 LITE_SHM_EXCLUSI
ccc0: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a VE.** </ul>.**.*
ccd0: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 * When unlocking
cce0: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 , the same SHARE
ccf0: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 D or EXCLUSIVE f
cd00: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 lag must be supp
cd10: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 lied as.** was g
cd20: 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 iven no the corr
cd30: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 esponding lock.
cd40: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d .**.** The xShm
cd50: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 Lock method can
cd60: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 transition betwe
cd70: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 en unlocked and
cd80: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 SHARED or.** bet
cd90: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e ween unlocked an
cda0: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 d EXCLUSIVE. It
cdb0: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 cannot transiti
cdc0: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 on between SHARE
cdd0: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 D.** and EXCLUSI
cde0: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 VE..*/.#define S
cdf0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b QLITE_SHM_UNLOCK
ce00: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
ce10: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
ce20: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 2.#defi
ce30: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 ne SQLITE_SHM_SH
ce40: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 ARED 4.#de
ce50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
ce60: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a EXCLUSIVE 8..
ce70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
ce80: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b Maximum xShmLock
ce90: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 index.**.** The
cea0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
ceb0: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f on [sqlite3_io_
cec0: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 methods] may use
ced0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 values.** betwe
cee0: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 en 0 and this up
cef0: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 per bound as its
cf00: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 "offset" argume
cf10: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 nt..** The SQLit
cf20: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 e core will neve
cf30: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 r attempt to acq
cf40: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 uire or release
cf50: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 a.** lock outsid
cf60: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a e of this range.
cf70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
cf80: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 E_SHM_NLOCK
cf90: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8.../*.** CAP
cfa0: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a I3REF: Initializ
cfb0: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 e The SQLite Lib
cfc0: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rary.**.** ^The
cfd0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
cfe0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 ze() routine ini
cff0: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 tializes the.**
d000: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 SQLite library.
d010: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 ^The sqlite3_sh
d020: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 utdown() routine
d030: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 .** deallocates
d040: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 any resources th
d050: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 at were allocate
d060: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 d by sqlite3_ini
d070: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 tialize()..** Th
d080: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
d090: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 designed to aid
d0a0: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 in process init
d0b0: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a ialization and.*
d0c0: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d * shutdown on em
d0d0: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 bedded systems.
d0e0: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 Workstation app
d0f0: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a lications using.
d100: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c ** SQLite normal
d110: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 ly do not need t
d120: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 o invoke either
d130: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
d140: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 s..**.** A call
d150: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 to sqlite3_initi
d160: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 alize() is an "e
d170: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 ffective" call i
d180: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 f it is.** the f
d190: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 irst time sqlite
d1a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
d1b0: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 s invoked during
d1c0: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 the lifetime of
d1d0: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c .** the process,
d1e0: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 or if it is the
d1f0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 first time sqli
d200: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
d210: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 is invoked.** f
d220: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 ollowing a call
d230: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 to sqlite3_shutd
d240: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 own(). ^(Only a
d250: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c n effective call
d260: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 .** of sqlite3_i
d270: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 nitialize() does
d280: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 any initializat
d290: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ion. All other
d2a0: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 calls.** are har
d2b0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a mless no-ops.)^.
d2c0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
d2d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
d2e0: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 () is an "effect
d2f0: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 ive" call if it
d300: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 is the first.**
d310: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
d320: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 shutdown() since
d330: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 the last sqlite
d340: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 3_initialize().
d350: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 ^(Only.** an ef
d360: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 fective call to
d370: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
d380: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e () does any dein
d390: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a itialization..**
d3a0: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 All other valid
d3b0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
d3c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 3_shutdown() are
d3d0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 harmless no-ops
d3e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 .)^.**.** The sq
d3f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
d400: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
d410: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 threadsafe, but
d420: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
d430: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 ().** is not. T
d440: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 he sqlite3_shutd
d450: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 own() interface
d460: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c must only be cal
d470: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 led from a.** si
d480: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c ngle thread. Al
d490: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 l open [database
d4a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 connections] mu
d4b0: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 st be closed and
d4c0: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 all.** other SQ
d4d0: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d Lite resources m
d4e0: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 ust be deallocat
d4f0: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f ed prior to invo
d500: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f king.** sqlite3_
d510: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a shutdown()..**.*
d520: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 * Among other th
d530: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 ings, ^sqlite3_i
d540: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c nitialize() will
d550: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 invoke.** sqlit
d560: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 e3_os_init(). S
d570: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 imilarly, ^sqlit
d580: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a e3_shutdown().**
d590: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c will invoke sql
d5a0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a ite3_os_end()..*
d5b0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
d5c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 3_initialize() r
d5d0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b outine returns [
d5e0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
d5f0: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f ccess..** ^If fo
d600: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 r some reason, s
d610: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
d620: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f e() is unable to
d630: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 initialize.** t
d640: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 he library (perh
d650: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 aps it is unable
d660: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e to allocate a n
d670: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 eeded resource s
d680: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 uch.** as a mute
d690: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e x) it returns an
d6a0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 [error code] ot
d6b0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
d6c0: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _OK]..**.** ^The
d6d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
d6e0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ize() routine is
d6f0: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c called internal
d700: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 ly by many other
d710: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
d720: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e faces so that an
d730: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 application usu
d740: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 ally does not ne
d750: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 ed to.** invoke
d760: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
d770: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 ze() directly.
d780: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 For example, [sq
d790: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a lite3_open()].**
d7a0: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 calls sqlite3_i
d7b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 nitialize() so t
d7c0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
d7d0: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 y will be automa
d7e0: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 tically.** initi
d7f0: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c alized when [sql
d800: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 ite3_open()] is
d810: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 called if it has
d820: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 not be initiali
d830: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 zed.** already.
d840: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 ^However, if SQ
d850: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
d860: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 with the [SQLIT
d870: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d E_OMIT_AUTOINIT]
d880: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
d890: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 option, then th
d8a0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c e automatic call
d8b0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 s to sqlite3_ini
d8c0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 tialize().** are
d8d0: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 omitted and the
d8e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
d8f0: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 t call sqlite3_i
d900: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
d910: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f ctly.** prior to
d920: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 using any other
d930: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
d940: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 e. For maximum
d950: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 portability,.**
d960: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 it is recommende
d970: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 d that applicati
d980: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b ons always invok
d990: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
d9a0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 lize().** direct
d9b0: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e ly prior to usin
d9c0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 g any other SQLi
d9d0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 te interface. F
d9e0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a uture releases.*
d9f0: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 * of SQLite may
da00: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 require this. I
da10: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
da20: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 he behavior exhi
da30: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 bited.** when SQ
da40: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
da50: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d with [SQLITE_OM
da60: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 IT_AUTOINIT] mig
da70: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a ht become the.**
da80: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f default behavio
da90: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 r in some future
daa0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
dab0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 te..**.** The sq
dac0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
dad0: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 routine does ope
dae0: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
daf0: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 ecific.** initia
db00: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 lization of the
db10: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 SQLite library.
db20: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
db30: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 end().** routine
db40: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 undoes the effe
db50: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 ct of sqlite3_os
db60: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 _init(). Typica
db70: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f l tasks.** perfo
db80: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f rmed by these ro
db90: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 utines include a
dba0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 llocation or dea
dbb0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 llocation.** of
dbc0: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 static resources
dbd0: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e , initialization
dbe0: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 of global varia
dbf0: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 bles,.** setting
dc00: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 up a default [s
dc10: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 qlite3_vfs] modu
dc20: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 le, or setting u
dc30: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 p.** a default c
dc40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 onfiguration usi
dc50: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ng [sqlite3_conf
dc60: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ig()]..**.** The
dc70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
dc80: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 uld never invoke
dc90: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f either sqlite3_
dca0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 os_init().** or
dcb0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
dcc0: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 directly. The
dcd0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
dce0: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a ld only invoke.*
dcf0: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 * sqlite3_initia
dd00: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 lize() and sqlit
dd10: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
dd20: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
dd30: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 nit().** interfa
dd40: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 ce is called aut
dd50: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 omatically by sq
dd60: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
dd70: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 () and.** sqlite
dd80: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 3_os_end() is ca
dd90: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f lled by sqlite3_
dda0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 shutdown(). App
ddb0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c ropriate.** impl
ddc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 ementations for
ddd0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
dde0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 ) and sqlite3_os
ddf0: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 _end().** are bu
de00: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 ilt into SQLite
de10: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 when it is compi
de20: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 led for Unix, Wi
de30: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a ndows, or OS/2..
de40: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 ** When [custom
de50: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 builds | built f
de60: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 or other platfor
de70: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 ms].** (using th
de80: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 e [SQLITE_OS_OTH
de90: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 ER=1] compile-ti
dea0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 me.** option) th
deb0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
dec0: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 st supply a suit
ded0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 able implementat
dee0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 ion for.** sqlit
def0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 e3_os_init() and
df00: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
df10: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 ). An applicati
df20: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 on-supplied.** i
df30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
df40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
df50: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 () or sqlite3_os
df60: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 _end().** must r
df70: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
df80: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 ] on success and
df90: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 some other [err
dfa0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a or code] upon.**
dfb0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 failure..*/.int
dfc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
dfd0: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 ize(void);.int s
dfe0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
dff0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
e000: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 e3_os_init(void)
e010: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 ;.int sqlite3_os
e020: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a _end(void);../*.
e030: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
e040: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c figuring The SQL
e050: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a ite Library.**.*
e060: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
e070: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
e080: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 is used to make
e090: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 global configur
e0a0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 ation.** changes
e0b0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 to SQLite in or
e0c0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 der to tune SQLi
e0d0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 te to the specif
e0e0: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 ic needs of.** t
e0f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
e100: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e The default con
e110: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 figuration is re
e120: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f commended for mo
e130: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f st.** applicatio
e140: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 ns and so this r
e150: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c outine is usuall
e160: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e y not necessary.
e170: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 It is.** provi
e180: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 ded to support r
e190: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 are applications
e1a0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 with unusual ne
e1b0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 eds..**.** The s
e1c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
e1d0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
e1e0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 threadsafe. Th
e1f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
e200: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 must insure tha
e210: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 t no other SQLit
e220: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 e interfaces are
e230: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 invoked by othe
e240: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 r.** threads whi
e250: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 le sqlite3_confi
e260: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 g() is running.
e270: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 Furthermore, sq
e280: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a lite3_config().*
e290: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e * may only be in
e2a0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c voked prior to l
e2b0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a ibrary initializ
e2c0: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b ation using.** [
e2d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
e2e0: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 ze()] or after s
e2f0: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 hutdown by [sqli
e300: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e te3_shutdown()].
e310: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
e320: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c config() is call
e330: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 ed after [sqlite
e340: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 3_initialize()]
e350: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 and before.** [s
e360: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
e370: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 )] then it will
e380: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 return SQLITE_MI
e390: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 SUSE..** Note, h
e3a0: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 owever, that ^sq
e3b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 lite3_config() c
e3c0: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 an be called as
e3d0: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 part of the.** i
e3e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
e3f0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
e400: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 defined [sqlite3
e410: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a _os_init()]..**.
e420: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
e430: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
e440: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 _config() is an
e450: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 integer.** [conf
e460: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
e470: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 ] that determine
e480: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 s.** what proper
e490: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 ty of SQLite is
e4a0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 to be configured
e4b0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 . Subsequent ar
e4c0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 guments.** vary
e4d0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
e4e0: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 [configuration
e4f0: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 option].** in th
e500: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
e510: 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 ..**.** ^When a
e520: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
e530: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c tion is set, sql
e540: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 ite3_config() re
e550: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
e560: 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 ]..** ^If the op
e570: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 tion is unknown
e580: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 or SQLite is una
e590: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f ble to set the o
e5a0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 ption.** then th
e5b0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
e5c0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 ns a non-zero [e
e5d0: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 rror code]..*/.i
e5e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 nt sqlite3_confi
e5f0: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a g(int, ...);../*
e600: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
e610: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 nfigure database
e620: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a connections.**.
e630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 ** The sqlite3_d
e640: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 b_config() inter
e650: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
e660: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 make configurati
e670: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f on.** changes to
e680: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
e690: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 nection]. The i
e6a0: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 nterface is simi
e6b0: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lar to.** [sqlit
e6c0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 e3_config()] exc
e6d0: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 ept that the cha
e6e0: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 nges apply to a
e6f0: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 single.** [datab
e700: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
e710: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 (specified in th
e720: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
e730: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 )..**.** The sec
e740: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
e750: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
e760: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 g(D,V,...) is t
e770: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 he.** [SQLITE_DB
e780: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
e790: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e | configuration
e7a0: 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 verb] - an inte
e7b0: 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 ger code .** tha
e7c0: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 t indicates what
e7d0: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b aspect of the [
e7e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
e7f0: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f ion] is being co
e800: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 nfigured..** Sub
e810: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 sequent argument
e820: 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 s vary depending
e830: 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 on the configur
e840: 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a ation verb..**.*
e850: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
e860: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
e870: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
e880: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a if and only if.
e890: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 ** the call is c
e8a0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 onsidered succes
e8b0: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c sful..*/.int sql
e8c0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 ite3_db_config(s
e8d0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c qlite3*, int op,
e8e0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
e8f0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
e900: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e llocation Routin
e910: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 es.**.** An inst
e920: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
e930: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
e940: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 interface betwee
e950: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 n SQLite.** and
e960: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
e970: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
e980: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ines..**.** This
e990: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 object is used
e9a0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 in only one plac
e9b0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 e in the SQLite
e9c0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 interface..** A
e9d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
e9e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
e9f0: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 bject is the arg
ea00: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c ument to.** [sql
ea10: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
ea20: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 hen the configur
ea30: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a ation option is.
ea40: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
ea50: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 G_MALLOC] or [SQ
ea60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
ea70: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 ALLOC]. .** By
ea80: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 creating an inst
ea90: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
eaa0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 ect.** and passi
eab0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
eac0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 3_config]([SQLIT
ead0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
eae0: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 ).** during conf
eaf0: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 iguration, an ap
eb00: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 plication can sp
eb10: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
eb20: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 tive.** memory a
eb30: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
eb40: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 tem for SQLite t
eb50: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 o use for all of
eb60: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 its.** dynamic
eb70: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a memory needs..**
eb80: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 .** Note that SQ
eb90: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 Lite comes with
eba0: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 several [built-i
ebb0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
ebc0: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 ors].** that are
ebd0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 perfectly adequ
ebe0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 ate for the over
ebf0: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 whelming majorit
ec00: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
ec10: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 s.** and that th
ec20: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c is object is onl
ec30: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 y useful to a ti
ec40: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 ny minority of a
ec50: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 pplications.** w
ec60: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 ith specialized
ec70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
ec80: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 n requirements.
ec90: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a This object is.
eca0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 ** also used dur
ecb0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 ing testing of S
ecc0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
ecd0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 o specify an alt
ece0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
ecf0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 ry allocator tha
ed00: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f t simulates memo
ed10: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 ry out-of-memory
ed20: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a conditions in.*
ed30: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 * order to verif
ed40: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 y that SQLite re
ed50: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c covers gracefull
ed60: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 y from such.** c
ed70: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a onditions..**.**
ed80: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 The xMalloc, xR
ed90: 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 ealloc, and xFre
eda0: 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 e methods must w
edb0: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 ork like the.**
edc0: 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f malloc(), reallo
edd0: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
ede0: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 unctions from th
edf0: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
ee00: 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 rary..** ^SQLite
ee10: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
ee20: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
ee30: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c ment to.** xReal
ee40: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 loc is always a
ee50: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
ee60: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 y a prior call t
ee70: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a o xRoundup..**.*
ee80: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 * xSize should r
ee90: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 eturn the alloca
eea0: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 ted size of a me
eeb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
eec0: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 ** previously ob
eed0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c tained from xMal
eee0: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e loc or xRealloc.
eef0: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 The allocated
ef00: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 size.** is alway
ef10: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 s at least as bi
ef20: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 g as the request
ef30: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 ed size but may
ef40: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a be larger..**.**
ef50: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 The xRoundup me
ef60: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 thod returns wha
ef70: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 t would be the a
ef80: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 llocated size of
ef90: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c .** a memory all
efa0: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 ocation given a
efb0: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 particular reque
efc0: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 sted size. Most
efd0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
efe0: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d ators round up m
eff0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
f000: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 s at least to th
f010: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a e next multiple.
f020: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 ** of 8. Some a
f030: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
f040: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d up to a larger m
f050: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 ultiple or to a
f060: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 power of 2..** E
f070: 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f very memory allo
f080: 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 cation request c
f090: 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 oming in through
f0a0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
f0b0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
f0c0: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 e3_realloc()] fi
f0d0: 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 rst calls xRound
f0e0: 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 up. If xRoundup
f0f0: 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 returns 0, .**
f100: 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 that causes the
f110: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 corresponding me
f120: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
f130: 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 to fail..**.** T
f140: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 he xInit method
f150: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 initializes the
f160: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
f170: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c . (For example,
f180: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c .** it might all
f190: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 ocate any requir
f1a0: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 e mutexes or ini
f1b0: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c tialize internal
f1c0: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 data.** structu
f1d0: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 res. The xShutd
f1e0: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e own method is in
f1f0: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c voked (indirectl
f200: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 y) by.** [sqlite
f210: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 3_shutdown()] an
f220: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 d should dealloc
f230: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 ate any resource
f240: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 s acquired.** by
f250: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 xInit. The pAp
f260: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 pData pointer is
f270: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c used as the onl
f280: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a y parameter to.*
f290: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 * xInit and xShu
f2a0: 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c tdown..**.** SQL
f2b0: 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 ite holds the [S
f2c0: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
f2d0: 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 IC_MASTER] mutex
f2e0: 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 when it invokes
f2f0: 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 .** the xInit me
f300: 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e thod, so the xIn
f310: 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e it method need n
f320: 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 ot be threadsafe
f330: 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 . The.** xShutd
f340: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e own method is on
f350: 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b ly called from [
f360: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
f370: 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a ()] so it does.*
f380: 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 * not need to be
f390: 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 threadsafe eith
f3a0: 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 er. For all oth
f3b0: 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 er methods, SQLi
f3c0: 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 te.** holds the
f3d0: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 [SQLITE_MUTEX_ST
f3e0: 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 ATIC_MEM] mutex
f3f0: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a as long as the.*
f400: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
f410: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 _MEMSTATUS] conf
f420: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
f430: 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 is turned on (w
f440: 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 hich.** it is by
f450: 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f default) and so
f460: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 the methods are
f470: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 automatically s
f480: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f erialized..** Ho
f490: 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 wever, if [SQLIT
f4a0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
f4b0: 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c US] is disabled,
f4c0: 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a then the other.
f4d0: 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 ** methods must
f4e0: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 be threadsafe or
f4f0: 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 else make their
f500: 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 own arrangement
f510: 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 s for.** seriali
f520: 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 zation..**.** SQ
f530: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
f540: 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d invoke xInit() m
f550: 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 ore than once wi
f560: 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 thout an interve
f570: 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 ning.** call to
f580: 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a xShutdown()..*/.
f590: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
f5a0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
f5b0: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ds sqlite3_mem_m
f5c0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
f5d0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
f5e0: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ds {. void *(*x
f5f0: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 Malloc)(int);
f600: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 /* Memory
f610: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 allocation funct
f620: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a ion */. void (*
f630: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 xFree)(void*);
f640: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 /* Free
f650: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 a prior allocati
f660: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a on */. void *(*
f670: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c xRealloc)(void*,
f680: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 int); /* Resize
f690: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
f6a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 /. int (*xSize)
f6b0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
f6c0: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 /* Return the
f6d0: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f size of an allo
f6e0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
f6f0: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 (*xRoundup)(int)
f700: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f ; /* Ro
f710: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 und up request s
f720: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f ize to allocatio
f730: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 n size */. int
f740: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b (*xInit)(void*);
f750: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e /* In
f760: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d itialize the mem
f770: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f ory allocator */
f780: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 . void (*xShutd
f790: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 own)(void*);
f7a0: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a /* Deinitializ
f7b0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
f7c0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
f7d0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
f7e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 /* Ar
f7f0: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 gument to xInit(
f800: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 ) and xShutdown(
f810: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ) */.};../*.** C
f820: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
f830: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a ration Options.*
f840: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e * KEYWORDS: {con
f850: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
f860: 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 n}.**.** These c
f870: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
f880: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
f890: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
f8a0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
f8b0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
f8c0: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
f8d0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c ment to the [sql
f8e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
f8f0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
f900: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f New configuratio
f910: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 n options may be
f920: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
f930: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
f940: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 ite..** Existing
f950: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
f960: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 ptions might be
f970: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 discontinued. A
f980: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
f990: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 hould check the
f9a0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d return code from
f9b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
f9c0: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ()] to make sure
f9d0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c that.** the cal
f9e0: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b l worked. The [
f9f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
fa00: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
fa10: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e return a.** non
fa20: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
fa30: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 e] if a disconti
fa40: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 nued or unsuppor
fa50: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ted configuratio
fa60: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 n option.** is i
fa70: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 nvoked..**.** <d
fa80: 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 l>.** [[SQLITE_C
fa90: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
faa0: 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AD]] <dt>SQLITE_
fab0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
fac0: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAD</dt>.** <dd>
fad0: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
fae0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
faf0: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
fb00: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
fb10: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
fb20: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 ] to Single-thre
fb30: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
fb40: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
fb50: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 .** all mutexing
fb60: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 and puts SQLite
fb70: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 into a mode whe
fb80: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 re it can only b
fb90: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 e used.** by a s
fba0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 ingle thread.
fbb0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
fbc0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
fbd0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
fbe0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
fbf0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
fc00: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
fc10: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
fc20: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 ot possible to c
fc30: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 hange the [threa
fc40: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 ding mode] from
fc50: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 its default.** v
fc60: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 alue of Single-t
fc70: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 hread and so [sq
fc80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
fc90: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 will return .**
fca0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
fcb0: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 f called with th
fcc0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
fcd0: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 SINGLETHREAD.**
fce0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
fcf0: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
fd00: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
fd10: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c _MULTITHREAD]] <
fd20: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
fd30: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 _MULTITHREAD</dt
fd40: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
fd50: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
fd60: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
fd70: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
fd80: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
fd90: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 ding mode] to Mu
fda0: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 lti-thread. In
fdb0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
fdc0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 disables.** mute
fdd0: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 xing on [databas
fde0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
fdf0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
fe00: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
fe10: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
fe20: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c on is responsibl
fe30: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e e for serializin
fe40: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b g access to.** [
fe50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
fe60: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
fe70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e red statements].
fe80: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 But other mute
fe90: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
fea0: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 ed so that SQLit
feb0: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 e will be safe t
fec0: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 o use in a multi
fed0: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 -threaded.** env
fee0: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 ironment as long
fef0: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 as no two threa
ff00: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 ds attempt to us
ff10: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 e the same.** [d
ff20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
ff30: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 on] at the same
ff40: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 time. ^If SQLit
ff50: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
ff60: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
ff70: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
ff80: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
ff90: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
ffa0: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
ffb0: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 it is not possib
ffc0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 le to set the Mu
ffd0: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 lti-thread [thre
ffe0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a ading mode] and.
fff0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
10000 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ig()] will retur
10010 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
10020 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 if called with
10030 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f the.** SQLITE_CO
10040 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
10050 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
10060 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
10070 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
10080 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c G_SERIALIZED]] <
10090 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
100a0 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e _SERIALIZED</dt>
100b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
100c0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
100d0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
100e0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
100f0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
10100 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 ing mode] to Ser
10110 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 ialized. In othe
10120 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 r words, this op
10130 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 tion enables.**
10140 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c all mutexes incl
10150 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 uding the recurs
10160 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f ive.** mutexes o
10170 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
10180 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 ection] and [pre
10190 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
101a0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 objects..** In
101b0 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 this mode (which
101c0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 is the default
101d0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
101e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
101f0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
10200 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 FE=1]) the SQLit
10210 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 e library will i
10220 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 tself serialize
10230 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 access.** to [da
10240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
10250 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 ns] and [prepare
10260 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f d statements] so
10270 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 that the.** app
10280 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 lication is free
10290 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 to use the same
102a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
102b0 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a ction] or the.**
102c0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 same [prepared
102d0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 statement] in di
102e0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 fferent threads
102f0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
10300 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 ..** ^If SQLite
10310 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
10320 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
10330 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
10340 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
10350 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
10360 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
10370 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
10380 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 to set the Seri
10390 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
103a0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b g mode] and.** [
103b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
103c0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 ] will return [S
103d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
103e0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a called with the.
103f0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
10400 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 _SERIALIZED conf
10410 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
10420 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
10430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
10440 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 LOC]] <dt>SQLITE
10450 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f _CONFIG_MALLOC</
10460 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
10470 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
10480 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
10490 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
104a0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
104b0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
104c0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
104d0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
104e0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
104f0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e cifies.** altern
10500 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
10510 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
10520 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 n routines to be
10530 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f used in place o
10540 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 f.** the memory
10550 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
10560 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
10570 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 QLite.)^ ^SQLite
10580 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 makes.** its ow
10590 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f n private copy o
105a0 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 f the content of
105b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
105c0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 m_methods] struc
105d0 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 ture.** before t
105e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
105f0 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 ig()] call retur
10600 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ns.</dd>.**.** [
10610 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
10620 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 ETMALLOC]] <dt>S
10630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
10640 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
10650 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
10660 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
10670 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
10680 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
10690 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
106a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
106b0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
106c0 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c cture. The [sql
106d0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
106e0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 ].** structure i
106f0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 s filled with th
10700 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 e currently defi
10710 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ned memory alloc
10720 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 ation routines.)
10730 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ^.** This option
10740 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
10750 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
10760 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ault memory allo
10770 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e cation.** routin
10780 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 es with a wrappe
10790 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f r that simulatio
107a0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ns memory alloca
107b0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a tion failure or.
107c0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 ** tracks memory
107d0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d usage, for exam
107e0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ple. </dd>.**.**
107f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
10800 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 _MEMSTATUS]] <dt
10810 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
10820 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a EMSTATUS</dt>.**
10830 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
10840 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 on takes single
10850 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
10860 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 int, interprete
10870 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 d as a .** boole
10880 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 an, which enable
10890 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
108a0 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 e collection of
108b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
108c0 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 n .** statistics
108d0 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 . ^(When memory
108e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
108f0 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c stics are disabl
10900 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c ed, the .** foll
10910 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 owing SQLite int
10920 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e erfaces become n
10930 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a on-operational:.
10940 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c ** <ul>.** <
10950 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d li> [sqlite3_mem
10960 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 ory_used()].**
10970 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
10980 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
10990 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
109a0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
109b0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 limit64()].**
109c0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 <li> [sqlite3_st
109d0 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 atus()].** </u
109e0 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 l>)^.** ^Memory
109f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
10a00 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 stics are enable
10a10 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c d by default unl
10a20 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a ess SQLite is.**
10a30 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
10a40 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d SQLITE_DEFAULT_M
10a50 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 EMSTATUS]=0 in w
10a60 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 hich case memory
10a70 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 .** allocation s
10a80 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 tatistics are di
10a90 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
10aa0 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a t..** </dd>.**.*
10ab0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
10ac0 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e G_SCRATCH]] <dt>
10ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
10ae0 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 RATCH</dt>.** <d
10af0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
10b00 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
10b10 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
10b20 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e that SQLite can
10b30 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 use for.** scra
10b40 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 tch memory. The
10b50 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
10b60 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 uments: A point
10b70 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 er an 8-byte.**
10b80 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 aligned memory b
10b90 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 uffer from which
10ba0 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c the scratch all
10bb0 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 ocations will be
10bc0 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 .** drawn, the s
10bd0 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 ize of each scra
10be0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 tch allocation (
10bf0 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 sz),.** and the
10c00 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
10c10 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 f scratch alloca
10c20 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 tions (N). The
10c30 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d sz.** argument m
10c40 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c ust be a multipl
10c50 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 e of 16..** The
10c60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
10c70 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 ust be a pointer
10c80 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c to an 8-byte al
10c90 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 igned buffer.**
10ca0 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e of at least sz*N
10cb0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
10cc0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c ..** ^SQLite wil
10cd0 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 l use no more th
10ce0 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 an two scratch b
10cf0 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 uffers per threa
10d00 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 d. So.** N shou
10d10 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 ld be set to twi
10d20 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 ce the expected
10d30 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
10d40 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 f threads..** ^S
10d50 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
10d60 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 require a scrat
10d70 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 ch buffer that i
10d80 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a s more than 6.**
10d90 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 times the datab
10da0 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e ase page size. ^
10db0 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 If SQLite needs
10dc0 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c needs additional
10dd0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f .** scratch memo
10de0 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 ry beyond what i
10df0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 s provided by th
10e00 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e is configuration
10e10 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a option, then .*
10e20 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
10e30 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 c()] will be use
10e40 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 d to obtain the
10e50 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f memory needed.</
10e60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
10e70 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
10e80 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 CHE]] <dt>SQLITE
10e90 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
10ea0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
10eb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 This option spec
10ec0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
10ed0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 emory buffer tha
10ee0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 t SQLite can use
10ef0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 for.** the data
10f00 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 base page cache
10f10 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 with the default
10f20 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c page cache impl
10f30 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a ementation. .**
10f40 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 This configurat
10f50 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 ion should not b
10f60 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 e used if an app
10f70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 lication-define
10f80 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d page.** cache im
10f90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
10fa0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 loaded using the
10fb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
10fc0 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a CACHE2 option..*
10fd0 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 * There are thre
10fe0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 e arguments to t
10ff0 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f his option: A po
11000 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 inter to 8-byte
11010 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 aligned.** memor
11020 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 y, the size of e
11030 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 ach page buffer
11040 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 (sz), and the nu
11050 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e mber of pages (N
11060 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 )..** The sz arg
11070 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
11080 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
11090 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 largest database
110a0 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 page.** (a powe
110b0 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e r of two between
110c0 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 512 and 32768)
110d0 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 plus a little ex
110e0 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 tra for each.**
110f0 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 page header. ^T
11100 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 he page header s
11110 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 ize is 20 to 40
11120 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 bytes depending
11130 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 on.** the host a
11140 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 rchitecture. ^I
11150 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 t is harmless, a
11160 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 part from the wa
11170 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 sted memory,.**
11180 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 to make sz a lit
11190 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 tle too large.
111a0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 The first.** arg
111b0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 ument should poi
111c0 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 nt to an allocat
111d0 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 ion of at least
111e0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 sz*N bytes of me
111f0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 mory..** ^SQLite
11200 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 will use the me
11210 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 mory provided by
11220 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
11230 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 ent to satisfy i
11240 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 ts.** memory nee
11250 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 ds for the first
11260 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 N pages that it
11270 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 adds to cache.
11280 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a ^If additional.
11290 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 ** page cache me
112a0 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 mory is needed b
112b0 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
112c0 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f ovided by this o
112d0 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 ption, then.** S
112e0 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 QLite goes to [s
112f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
11300 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f for the additio
11310 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 nal storage spac
11320 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 e..** The pointe
11330 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 r in the first a
11340 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 rgument must.**
11350 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
11360 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8-byte boundary
11370 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 or subsequent b
11380 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 ehavior of SQLit
11390 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 e.** will be und
113a0 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a efined.</dd>.**.
113b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
113c0 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 IG_HEAP]] <dt>SQ
113d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
113e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
113f0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
11400 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
11410 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
11420 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
11430 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 .** for all of i
11440 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ts dynamic memor
11450 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
11460 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 ds beyond those
11470 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 provided.** for
11480 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
11490 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b G_SCRATCH] and [
114a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
114b0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 GECACHE]..** The
114c0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
114d0 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 uments: An 8-byt
114e0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 e aligned pointe
114f0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c r to the memory,
11500 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
11510 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d f bytes in the m
11520 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e emory buffer, an
11530 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c d the minimum al
11540 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a location size..*
11550 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 * ^If the first
11560 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d pointer (the mem
11570 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 ory pointer) is
11580 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 NULL, then SQLit
11590 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 e reverts.** to
115a0 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c using its defaul
115b0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
115c0 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d or (the system m
115d0 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e alloc() implemen
115e0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f tation),.** undo
115f0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e ing any prior in
11600 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c vocation of [SQL
11610 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
11620 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 C]. ^If the.**
11630 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 memory pointer i
11640 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 s not NULL and e
11650 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e ither [SQLITE_EN
11660 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 ABLE_MEMSYS3] or
11670 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
11680 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 LE_MEMSYS5] are
11690 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 defined, then th
116a0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 e alternative me
116b0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
116c0 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 r is engaged to
116d0 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 handle all of SQ
116e0 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c Lites memory all
116f0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a ocation needs..*
11700 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e * The first poin
11710 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
11720 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 pointer) must be
11730 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
11740 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 -byte.** boundar
11750 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 y or subsequent
11760 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
11770 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 te will be undef
11780 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e ined..** The min
11790 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 imum allocation
117a0 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 size is capped a
117b0 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 t 2**12. Reasona
117c0 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f ble values.** fo
117d0 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c r the minimum al
117e0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 location size ar
117f0 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 e 2**5 through 2
11800 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 **8.</dd>.**.**
11810 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
11820 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 MUTEX]] <dt>SQLI
11830 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c TE_CONFIG_MUTEX<
11840 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
11850 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
11860 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
11870 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
11880 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
11890 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
118a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
118b0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
118c0 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 . The argument
118d0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 specifies.** alt
118e0 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 ernative low-lev
118f0 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 el mutex routine
11900 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 s to be used in
11910 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 place.** the mut
11920 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c ex routines buil
11930 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e t into SQLite.)^
11940 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ^SQLite makes
11950 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a a copy of the.**
11960 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
11970 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
11980 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
11990 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c e before the cal
119a0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
119b0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 _config()] retur
119c0 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 ns. ^If SQLite i
119d0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
119e0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
119f0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
11a00 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
11a10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
11a20 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 tion then.** the
11a30 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 entire mutexing
11a40 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d subsystem is om
11a50 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 itted from the b
11a60 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 uild and hence c
11a70 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 alls to.** [sqli
11a80 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
11a90 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
11aa0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 NFIG_MUTEX confi
11ab0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
11ac0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b will.** return [
11ad0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f SQLITE_ERROR].</
11ae0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
11af0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
11b00 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f EX]] <dt>SQLITE_
11b10 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c CONFIG_GETMUTEX<
11b20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
11b30 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
11b40 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
11b50 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
11b60 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
11b70 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
11b80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
11b90 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
11ba0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 . The.** [sqlit
11bb0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
11bc0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 ].** structure i
11bd0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 s filled with th
11be0 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 e currently defi
11bf0 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e ned mutex routin
11c00 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 es.)^.** This op
11c10 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 tion can be used
11c20 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 to overload the
11c30 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 default mutex a
11c40 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 llocation.** rou
11c50 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 tines with a wra
11c60 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 pper used to tra
11c70 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 ck mutex usage f
11c80 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a or performance.*
11c90 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 * profiling or t
11ca0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d esting, for exam
11cb0 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 ple. ^If SQLit
11cc0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
11cd0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
11ce0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
11cf0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
11d00 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
11d10 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
11d20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 the entire mutex
11d30 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 ing subsystem is
11d40 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
11d50 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 e build and henc
11d60 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 e calls to.** [s
11d70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
11d80 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
11d90 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
11da0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
11db0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 ption will.** re
11dc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
11dd0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 OR].</dd>.**.**
11de0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
11df0 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e LOOKASIDE]] <dt>
11e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
11e10 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 OKASIDE</dt>.**
11e20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
11e30 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
11e40 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
11e50 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c rmine the defaul
11e60 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t.** memory allo
11e70 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c cation for the l
11e80 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
11e90 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 allocator on eac
11ea0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 h.** [database c
11eb0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 onnection]. The
11ec0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
11ed0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
11ee0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
11ef0 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 buffer slot and
11f00 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 the second is t
11f10 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
11f20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 slots allocated
11f30 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 to each database
11f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 connection.)^
11f50 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^(This option se
11f60 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 ts the.** <i>def
11f70 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 ault</i> lookasi
11f80 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 de size. The [SQ
11f90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
11fa0 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 OKASIDE].** verb
11fb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f to [sqlite3_db_
11fc0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 config()] can be
11fd0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 used to change
11fe0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a the lookaside.**
11ff0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
12000 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e n individual con
12010 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 nections.)^ </dd
12020 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
12030 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d _CONFIG_PCACHE2]
12040 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12050 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e FIG_PCACHE2</dt>
12060 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
12070 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
12080 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
12090 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
120a0 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 r to.** an [sqli
120b0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
120c0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 ds2] object. Th
120d0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 is object specif
120e0 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ies the interfac
120f0 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d e.** to a custom
12100 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c page cache impl
12110 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e ementation.)^ ^
12120 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
12130 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 opy of the.** ob
12140 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 ject and uses it
12150 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 for page cache
12160 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12170 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ns.</dd>.**.** [
12180 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
12190 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e ETPCACHE2]] <dt>
121a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
121b0 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a TPCACHE2</dt>.**
121c0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 <dd> ^(This opt
121d0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
121e0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
121f0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
12200 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 o an.** [sqlite3
12210 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
12220 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 ] object. SQLit
12230 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 e copies of the
12240 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 current.** page
12250 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
12260 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f tion into that o
12270 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a bject.)^ </dd>.*
12280 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
12290 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 NFIG_LOG]] <dt>S
122a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
122b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
122c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
122d0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 _LOG option take
122e0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a s two arguments:
122f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a a pointer to a.
12300 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ** function with
12310 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 a call signatur
12320 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 e of void(*)(voi
12330 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
12340 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 r*), .** and a p
12350 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 ointer to void.
12360 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e ^If the function
12370 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
12380 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 NULL, it is.** i
12390 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 nvoked by [sqlit
123a0 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f e3_log()] to pro
123b0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e cess each loggin
123c0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 g event. ^If th
123d0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f e.** function po
123e0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 inter is NULL, t
123f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 he [sqlite3_log(
12400 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 )] interface bec
12410 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a omes a no-op..**
12420 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 ^The void point
12430 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 er that is the s
12440 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
12450 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
12460 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 LOG is.** passed
12470 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 through as the
12480 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
12490 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
124a0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 on-defined logge
124b0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 r.** function wh
124c0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 enever that func
124d0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e tion is invoked.
124e0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ^The second pa
124f0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 rameter to.** th
12500 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
12510 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 n is a copy of t
12520 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
12530 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 er to the corres
12540 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 ponding.** [sqli
12550 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 te3_log()] call
12560 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 and is intended
12570 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 to be a [result
12580 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b code] or an.** [
12590 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
125a0 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 code]. ^The thi
125b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 rd parameter pas
125c0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 sed to the logge
125d0 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 r is.** log mess
125e0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 age after format
125f0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 ting via [sqlite
12600 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 3_snprintf()]..*
12610 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 * The SQLite log
12620 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 ging interface i
12630 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b s not reentrant;
12640 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 the logger func
12650 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 tion.** supplied
12660 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
12670 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 ion must not inv
12680 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 oke any SQLite i
12690 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 nterface..** In
126a0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 a multi-threaded
126b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 application, th
126c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
126d0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 fined logger.**
126e0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 function must be
126f0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 threadsafe. </d
12700 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
12710 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c E_CONFIG_URI]] <
12720 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
12730 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 _URI.** <dd> Thi
12740 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
12750 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
12760 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 of type int. If
12770 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a non-zero, then.
12780 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 ** URI handling
12790 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 is globally enab
127a0 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 led. If the para
127b0 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 meter is zero, t
127c0 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 hen URI handling
127d0 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 .** is globally
127e0 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 disabled. If URI
127f0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f handling is glo
12800 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 bally enabled, a
12810 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 ll filenames.**
12820 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 passed to [sqlit
12830 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
12840 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
12850 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
12860 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 ()] or.** specif
12870 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b ied as part of [
12880 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 ATTACH] commands
12890 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
128a0 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 as URIs, regard
128b0 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 less.** of wheth
128c0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 er or not the [S
128d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
128e0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e flag is set when
128f0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
12900 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
12910 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 pened. If it is
12920 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 globally disable
12930 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 d, filenames are
12940 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 .** only interpr
12950 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 eted as URIs if
12960 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f the SQLITE_OPEN_
12970 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 URI flag is set
12980 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 when the.** data
12990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
129a0 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 is opened. By de
129b0 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c fault, URI handl
129c0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a ing is globally.
129d0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 ** disabled. The
129e0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d default value m
129f0 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 ay be changed by
12a00 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 compiling with
12a10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 the.** [SQLITE_U
12a20 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 SE_URI] symbol d
12a30 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b efined..**.** [[
12a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
12a50 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f ACHE]] [[SQLITE_
12a60 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
12a70 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
12a80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 _CONFIG_PCACHE a
12a90 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 4e 49 nd SQLITE_CONFNI
12aa0 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c G_GETPCACHE.** <
12ab0 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e dd> These option
12ac0 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 s are obsolete a
12ad0 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 nd should not be
12ae0 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 used by new cod
12af0 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 e..** They are r
12b00 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b etained for back
12b10 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
12b20 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 ity but are now
12b30 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e no-ops..** </dl>
12b40 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
12b50 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
12b60 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 THREAD 1 /* ni
12b70 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
12b80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
12b90 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e THREAD 2 /* n
12ba0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
12bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
12bc0 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 ALIZED 3 /*
12bd0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nil */.#define S
12be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
12bf0 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a LOC 4 /*
12c00 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
12c10 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
12c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
12c30 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 ETMALLOC 5
12c40 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d /* sqlite3_mem_m
12c50 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
12c60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
12c70 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 _SCRATCH 6
12c80 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
12c90 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 sz, int N */.#de
12ca0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
12cb0 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 IG_PAGECACHE
12cc0 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 7 /* void*, in
12cd0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 t sz, int N */.#
12ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
12cf0 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 NFIG_HEAP
12d00 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 8 /* void*,
12d10 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d int nByte, int m
12d20 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 in */.#define SQ
12d30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
12d40 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 TATUS 9 /*
12d50 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 boolean */.#defi
12d60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
12d70 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 _MUTEX 10
12d80 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
12d90 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 ex_methods* */.#
12da0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
12db0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 NFIG_GETMUTEX
12dc0 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 11 /* sqlite3
12dd0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
12de0 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 */./* previously
12df0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 SQLITE_CONFIG_C
12e00 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 HUNKALLOC 12 whi
12e10 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 ch is now unused
12e20 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 . */ .#define SQ
12e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
12e40 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 ASIDE 13 /*
12e50 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 int int */.#defi
12e60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
12e70 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 _PCACHE 14
12e80 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 /* no-op */.#d
12e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
12ea0 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 FIG_GETPCACHE
12eb0 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 15 /* no-op */
12ec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
12ed0 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 CONFIG_LOG
12ee0 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 16 /* xFunc
12ef0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 , void* */.#defi
12f00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
12f10 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 _URI 17
12f20 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 /* int */.#def
12f30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
12f40 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 G_PCACHE2 1
12f50 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 8 /* sqlite3_pc
12f60 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a ache_methods2* *
12f70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
12f80 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
12f90 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 E2 19 /* sqli
12fa0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
12fb0 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 ds2* */../*.** C
12fc0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
12fd0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e e Connection Con
12fe0 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f figuration Optio
12ff0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 ns.**.** These c
13000 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
13010 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
13020 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
13030 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
13040 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
13050 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
13060 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
13070 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
13080 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
13090 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
130a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
130b0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
130c0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
130d0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
130e0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
130f0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
13100 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
13110 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
13120 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
13130 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
13140 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 from [sqlite3_db
13150 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 _config()] to ma
13160 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 ke sure that.**
13170 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e the call worked.
13180 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ^The [sqlite3_
13190 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
131a0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
131b0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
131c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
131d0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
131e0 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
131f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
13200 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
13210 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
13220 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
13230 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
13240 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
13250 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 s option takes t
13260 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 hree additional
13270 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
13280 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a etermine the .**
13290 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f [lookaside memo
132a0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f ry allocator] co
132b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 nfiguration for
132c0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
132d0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 nnection]..** ^T
132e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
132f0 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 t (the third par
13300 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
13310 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
13320 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 is a.** pointer
13330 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 to a memory buff
13340 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f er to use for lo
13350 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a okaside memory..
13360 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
13370 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 gument after the
13380 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
13390 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a _LOOKASIDE verb.
133a0 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 ** may be NULL i
133b0 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c n which case SQL
133c0 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 ite will allocat
133d0 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 e the.** lookasi
133e0 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 de buffer itself
133f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
13400 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 malloc()]. ^The
13410 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
13420 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
13430 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
13440 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e buffer slot. ^
13450 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
13460 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nt is the number
13470 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 of.** slots. T
13480 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 he size of the b
13490 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 uffer in the fir
134a0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 st argument must
134b0 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e be greater than
134c0 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 .** or equal to
134d0 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 the product of t
134e0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
134f0 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 ird arguments.
13500 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 The buffer.** mu
13510 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f st be aligned to
13520 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 an 8-byte bound
13530 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 ary. ^If the se
13540 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
13550 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e .** SQLITE_DBCON
13560 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 FIG_LOOKASIDE is
13570 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 not a multiple
13580 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 of 8, it is inte
13590 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 rnally.** rounde
135a0 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 d down to the ne
135b0 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 xt smaller multi
135c0 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 ple of 8. ^(The
135d0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
135e0 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 y.** configurati
135f0 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 on for a databas
13600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e e connection can
13610 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 only be changed
13620 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f when that.** co
13630 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 nnection is not
13640 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 currently using
13650 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
13660 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f , or in other wo
13670 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 rds.** when the
13680 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 "current value"
13690 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
136a0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 sqlite3_db_statu
136b0 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e s](D,[SQLITE_CON
136c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e FIG_LOOKASIDE],.
136d0 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 ..) is zero..**
136e0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 Any attempt to c
136f0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 hange the lookas
13700 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 ide memory confi
13710 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f guration when lo
13720 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 okaside.** memor
13730 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 y is in use leav
13740 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 es the configura
13750 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 tion unchanged a
13760 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b nd returns .** [
13770 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c SQLITE_BUSY].)^<
13780 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
13790 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
137a0 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a NABLE_FKEY</dt>.
137b0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
137c0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
137d0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
137e0 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e e the enforcemen
137f0 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e t of.** [foreign
13800 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 key constraints
13810 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 ]. There should
13820 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
13830 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
13840 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
13850 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
13860 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
13870 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 disable FK enfor
13880 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 cement,.** posit
13890 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b ive to enable FK
138a0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 enforcement or
138b0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 negative to leav
138c0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
138d0 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 .** unchanged.
138e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
138f0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
13900 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
13910 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
13920 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
13930 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
13940 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 her FK enforceme
13950 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a nt is off or on.
13960 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 ** following thi
13970 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 s call. The sec
13980 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 ond parameter ma
13990 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e y be a NULL poin
139a0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 ter, in.** which
139b0 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 case the FK enf
139c0 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 orcement setting
139d0 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 is not reported
139e0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a back. </dd>.**.
139f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
13a00 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 CONFIG_ENABLE_TR
13a10 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 IGGER</dt>.** <d
13a20 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
13a30 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c is used to enabl
13a40 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 e or disable [CR
13a50 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
13a60 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 riggers]..** The
13a70 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f re should be two
13a80 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
13a90 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 ments..** The fi
13aa0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
13ab0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
13ac0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
13ad0 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f triggers,.** po
13ae0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
13af0 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 triggers or neg
13b00 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 ative to leave t
13b10 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 he setting uncha
13b20 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 nged..** The sec
13b30 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
13b40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
13b50 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 integer into wh
13b60 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 ich.** is writte
13b70 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 n 0 or 1 to indi
13b80 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 cate whether tri
13b90 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c ggers are disabl
13ba0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a ed or enabled.**
13bb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
13bc0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
13bd0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 d parameter may
13be0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
13bf0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 r, in.** which c
13c00 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 ase the trigger
13c10 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
13c20 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
13c30 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a dd>.**.** </dl>.
13c40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
13c50 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
13c60 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 SIDE 1001
13c70 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e /* void* int in
13c80 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
13c90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
13ca0 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 BLE_FKEY 100
13cb0 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2 /* int int* *
13cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
13cd0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
13ce0 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 _TRIGGER 1003
13cf0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a /* int int* */..
13d00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
13d10 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 Enable Or Disab
13d20 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 le Extended Resu
13d30 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e lt Codes.**.** ^
13d40 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
13d50 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
13d60 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 s() routine enab
13d70 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
13d80 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 the.** [extended
13d90 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 result codes] f
13da0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 eature of SQLite
13db0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 . ^The extended
13dc0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 result.** codes
13dd0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 are disabled by
13de0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 default for hist
13df0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 orical compatibi
13e00 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c lity..*/.int sql
13e10 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
13e20 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 sult_codes(sqlit
13e30 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b e3*, int onoff);
13e40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
13e50 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f : Last Insert Ro
13e60 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 wid.**.** ^Each
13e70 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 entry in an SQLi
13e80 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 te table has a u
13e90 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 nique 64-bit sig
13ea0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b ned.** integer k
13eb0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 ey called the [R
13ec0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e OWID | "rowid"].
13ed0 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 ^The rowid is a
13ee0 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a lways available.
13ef0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 ** as an undecla
13f00 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 red column named
13f10 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 ROWID, OID, or
13f20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 _ROWID_ as long
13f30 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 as those.** name
13f40 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 s are not also u
13f50 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c sed by explicitl
13f60 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d y declared colum
13f70 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 ns. ^If.** the t
13f80 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d able has a colum
13f90 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 n of type [INTEG
13fa0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 ER PRIMARY KEY]
13fb0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e then that column
13fc0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 .** is another a
13fd0 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 lias for the row
13fe0 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 id..**.** ^This
13ff0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
14000 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 the [rowid] of t
14010 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a he most recent.*
14020 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e * successful [IN
14030 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 SERT] into the d
14040 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 atabase from the
14050 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
14060 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 ction].** in the
14070 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
14080 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20 ^As of SQLite
14090 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 version 3.7.7, t
140a0 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 his routines.**
140b0 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74 records the last
140c0 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66 insert rowid of
140d0 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74 both ordinary t
140e0 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75 ables and [virtu
140f0 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e al tables]..** ^
14100 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c If no successful
14110 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 [INSERT]s.** ha
14120 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 ve ever occurred
14130 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 on that databas
14140 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 e connection, ze
14150 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a ro is returned..
14160 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 **.** ^(If an [I
14170 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 NSERT] occurs wi
14180 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f thin a trigger o
14190 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 r within a [virt
141a0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 ual table].** me
141b0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 thod, then this
141c0 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 routine will ret
141d0 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 urn the [rowid]
141e0 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a of the inserted.
141f0 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 ** row as long a
14200 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 s the trigger or
14210 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d virtual table m
14220 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 ethod is running
14230 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 ..** But once th
14240 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 e trigger or vir
14250 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f tual table metho
14260 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 d ends, the valu
14270 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 e returned .** b
14280 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 y this routine r
14290 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 everts to what i
142a0 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 t was before the
142b0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 trigger or virt
142c0 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 ual.** table met
142d0 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a hod began.)^.**.
142e0 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 ** ^An [INSERT]
142f0 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 that fails due t
14300 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 o a constraint v
14310 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 iolation is not
14320 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 a.** successful
14330 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 [INSERT] and doe
14340 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
14350 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
14360 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 by this.** routi
14370 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 ne. ^Thus INSER
14380 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 T OR FAIL, INSER
14390 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 T OR IGNORE, INS
143a0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c ERT OR ROLLBACK,
143b0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f .** and INSERT O
143c0 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 R ABORT make no
143d0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 changes to the r
143e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
143f0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 his.** routine w
14400 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 hen their insert
14410 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 ion fails. ^(Wh
14420 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 en INSERT OR REP
14430 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 LACE.** encounte
14440 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 rs a constraint
14450 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f violation, it do
14460 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 es not fail. Th
14470 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 e.** INSERT cont
14480 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 inues to complet
14490 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 ion after deleti
144a0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 ng rows that cau
144b0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 sed.** the const
144c0 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f raint problem so
144d0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 INSERT OR REPLA
144e0 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 CE will always c
144f0 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 hange.** the ret
14500 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
14510 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a s interface.)^.*
14520 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 *.** ^For the pu
14530 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 rposes of this r
14540 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 outine, an [INSE
14550 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 RT] is considere
14560 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 d to.** be succe
14570 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 ssful even if it
14580 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 is subsequently
14590 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a rolled back..**
145a0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
145b0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 n is accessible
145c0 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 to SQL statement
145d0 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 s via the.** [la
145e0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
145f0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
14600 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
14610 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 rate thread perf
14620 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 orms a new [INSE
14630 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a RT] on the same.
14640 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
14650 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 ection while the
14660 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 [sqlite3_last_i
14670 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a nsert_rowid()].*
14680 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 * function is ru
14690 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 nning and thus c
146a0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 hanges the last
146b0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a insert [rowid],.
146c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 ** then the valu
146d0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 e returned by [s
146e0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
146f0 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a rt_rowid()] is.*
14700 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 * unpredictable
14710 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 and might not eq
14720 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f ual either the o
14730 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a ld or the new.**
14740 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f last insert [ro
14750 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 wid]..*/.sqlite3
14760 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c _int64 sqlite3_l
14770 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
14780 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
14790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 ** CAPI3REF: Cou
147a0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 nt The Number Of
147b0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a Rows Modified.*
147c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
147d0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
147e0 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 number of databa
147f0 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 se rows that wer
14800 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 e changed.** or
14810 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 inserted or dele
14820 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 ted by the most
14830 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 recently complet
14840 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ed SQL statement
14850 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 .** on the [data
14860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
14870 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
14880 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
14890 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 r..** ^(Only cha
148a0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 nges that are di
148b0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 rectly specified
148c0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d by the [INSERT]
148d0 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f , [UPDATE],.** o
148e0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
148f0 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 ment are counted
14900 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 . Auxiliary cha
14910 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a nges caused by.*
14920 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 * triggers or [f
14930 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
14940 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e ns] are not coun
14950 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a ted.)^ Use the.*
14960 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c * [sqlite3_total
14970 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 _changes()] func
14980 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 tion to find the
14990 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 total number of
149a0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c changes.** incl
149b0 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 uding changes ca
149c0 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 used by triggers
149d0 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 and foreign key
149e0 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 actions..**.**
149f0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 ^Changes to a vi
14a00 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 ew that are simu
14a10 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 lated by an [INS
14a20 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d TEAD OF trigger]
14a30 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e .** are not coun
14a40 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 ted. Only real
14a50 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 table changes ar
14a60 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a e counted..**.**
14a70 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 ^(A "row change
14a80 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f " is a change to
14a90 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 a single row of
14aa0 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a a single table.
14ab0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 ** caused by an
14ac0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 INSERT, DELETE,
14ad0 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d or UPDATE statem
14ae0 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a ent. Rows that.
14af0 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 ** are changed a
14b00 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f s side effects o
14b10 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 f [REPLACE] cons
14b20 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f traint resolutio
14b30 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 n,.** rollback,
14b40 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 ABORT processing
14b50 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 , [DROP TABLE],
14b60 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a or by any other.
14b70 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f ** mechanisms do
14b80 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 not count as di
14b90 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 rect row changes
14ba0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 .)^.**.** A "tri
14bb0 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 gger context" is
14bc0 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 a scope of exec
14bd0 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e ution that begin
14be0 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 s and.** ends wi
14bf0 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 th the script of
14c00 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 a [CREATE TRIGG
14c10 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a ER | trigger]. .
14c20 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 ** Most SQL stat
14c30 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 ements are.** ev
14c40 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 aluated outside
14c50 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 of any trigger.
14c60 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f This is the "to
14c70 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 p level".** trig
14c80 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 ger context. If
14c90 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 a trigger fires
14ca0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 from the top le
14cb0 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 vel, a.** new tr
14cc0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 igger context is
14cd0 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 entered for the
14ce0 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 duration of tha
14cf0 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 t one.** trigger
14d00 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 . Subtriggers c
14d10 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 reate subcontext
14d20 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 s for their dura
14d30 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c tion..**.** ^Cal
14d40 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 ling [sqlite3_ex
14d50 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ec()] or [sqlite
14d60 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 3_step()] recurs
14d70 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f ively does.** no
14d80 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 t create a new t
14d90 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a rigger context..
14da0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
14db0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
14dc0 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 number of direc
14dd0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e t row changes in
14de0 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 the.** most rec
14df0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ent INSERT, UPDA
14e00 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 TE, or DELETE st
14e10 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 atement within t
14e20 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 he same.** trigg
14e30 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a er context..**.*
14e40 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 * ^Thus, when ca
14e50 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f lled from the to
14e60 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 p level, this fu
14e70 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
14e80 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
14e90 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d changes in the m
14ea0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 ost recent INSER
14eb0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
14ec0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 LETE.** that als
14ed0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 o occurred at th
14ee0 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 e top level. ^(
14ef0 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 Within the body
14f00 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a of a trigger,.**
14f10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 the sqlite3_cha
14f20 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 nges() interface
14f30 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 can be called t
14f40 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 o find the numbe
14f50 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 r of.** changes
14f60 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
14f70 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 ntly completed I
14f80 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
14f90 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 r DELETE.** stat
14fa0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 ement within the
14fb0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d body of the sam
14fc0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f e trigger..** Ho
14fd0 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 wever, the numbe
14fe0 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 r returned does
14ff0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e not include chan
15000 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 ges.** caused by
15010 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e subtriggers sin
15020 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 ce those have th
15030 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e eir own context.
15040 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 )^.**.** See als
15050 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 o the [sqlite3_t
15060 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
15070 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a interface, the.*
15080 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 * [count_changes
15090 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 pragma], and th
150a0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c e [changes() SQL
150b0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a function]..**.*
150c0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
150d0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 thread makes cha
150e0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 nges on the same
150f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
15100 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 tion.** while [s
15110 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
15120 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 ] is running the
15130 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
15140 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 rned.** is unpre
15150 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 dictable and not
15160 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a meaningful..*/.
15170 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e int sqlite3_chan
15180 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
15190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
151a0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 Total Number Of
151b0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a Rows Modified.**
151c0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
151d0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
151e0 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 umber of row cha
151f0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b nges caused by [
15200 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 INSERT],.** [UPD
15210 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d ATE] or [DELETE]
15220 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 statements sinc
15230 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 e the [database
15240 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 connection] was
15250 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 opened..** ^(The
15260 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 count returned
15270 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c by sqlite3_total
15280 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 _changes() inclu
15290 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a des all changes.
152a0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 ** from all [CRE
152b0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 ATE TRIGGER | tr
152c0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 igger] contexts
152d0 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 and changes made
152e0 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 by.** [foreign
152f0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f key actions]. Ho
15300 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f wever,.** the co
15310 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 unt does not inc
15320 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 lude changes use
15330 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b d to implement [
15340 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 REPLACE] constra
15350 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c ints,.** do roll
15360 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 backs or ABORT p
15370 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 rocessing, or [D
15380 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 ROP TABLE] proce
15390 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 ssing. The.** c
153a0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e ount does not in
153b0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 clude rows of vi
153c0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e ews that fire an
153d0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 [INSTEAD OF tri
153e0 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 gger],.** though
153f0 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 if the INSTEAD
15400 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 OF trigger makes
15410 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 changes of its
15420 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 own, those chang
15430 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 es .** are count
15440 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 ed.)^.** ^The sq
15450 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
15460 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 ges() function c
15470 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 ounts the change
15480 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 s as soon as.**
15490 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 the statement th
154a0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 at makes them is
154b0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e completed (when
154c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 the statement h
154d0 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 andle.** is pass
154e0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ed to [sqlite3_r
154f0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 eset()] or [sqli
15500 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 te3_finalize()])
15510 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
15520 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 the [sqlite3_ch
15530 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
15540 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e ce, the.** [coun
15550 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 t_changes pragma
15560 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 ], and the [tota
15570 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 l_changes() SQL
15580 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
15590 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
155a0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
155b0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
155c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
155d0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
155e0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
155f0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
15600 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
15610 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 .** returned is
15620 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
15630 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
15640 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
15650 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 _total_changes(s
15660 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
15670 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 CAPI3REF: Inter
15680 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e rupt A Long-Runn
15690 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 ing Query.**.**
156a0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 ^This function c
156b0 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e auses any pendin
156c0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 g database opera
156d0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e tion to abort an
156e0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 d.** return at i
156f0 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f ts earliest oppo
15700 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f rtunity. This ro
15710 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c utine is typical
15720 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 ly.** called in
15730 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 response to a us
15740 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 er action such a
15750 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 s pressing "Canc
15760 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 el".** or Ctrl-C
15770 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 where the user
15780 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 wants a long que
15790 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 ry operation to
157a0 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 halt.** immediat
157b0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 ely..**.** ^It i
157c0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 s safe to call t
157d0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d his routine from
157e0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 a thread differ
157f0 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 ent from the.**
15800 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 thread that is c
15810 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 urrently running
15820 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 the database op
15830 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 eration. But it
15840 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 .** is not safe
15850 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
15860 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 tine with a [dat
15870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
15880 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f ] that.** is clo
15890 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f sed or might clo
158a0 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 se before sqlite
158b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 3_interrupt() re
158c0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 turns..**.** ^If
158d0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f an SQL operatio
158e0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 n is very nearly
158f0 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 finished at the
15900 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 time when.** sq
15910 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
15920 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 ) is called, the
15930 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 n it might not h
15940 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 ave an opportuni
15950 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 ty.** to be inte
15960 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 rrupted and migh
15970 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f t continue to co
15980 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 mpletion..**.**
15990 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f ^An SQL operatio
159a0 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 n that is interr
159b0 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 upted will retur
159c0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 n [SQLITE_INTERR
159d0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 UPT]..** ^If the
159e0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c interrupted SQL
159f0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e operation is an
15a00 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
15a10 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 or DELETE.** th
15a20 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 at is inside an
15a30 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 explicit transac
15a40 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 tion, then the e
15a50 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f ntire transactio
15a60 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c n.** will be rol
15a70 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 led back automat
15a80 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ically..**.** ^T
15a90 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
15aa0 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 rupt(D) call is
15ab0 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 in effect until
15ac0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 all currently ru
15ad0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 nning.** SQL sta
15ae0 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 tements on [data
15af0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
15b00 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 D complete. ^A
15b10 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 ny new SQL state
15b20 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
15b30 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
15b40 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
15b50 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 rrupt() call and
15b60 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 before the .**
15b70 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e running statemen
15b80 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 ts reaches zero
15b90 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 are interrupted
15ba0 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 as if they had b
15bb0 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 een.** running p
15bc0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 rior to the sqli
15bd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
15be0 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 call. ^New SQL
15bf0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
15c00 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
15c10 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 fter the running
15c20 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 statement count
15c30 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 reaches zero ar
15c40 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 e.** not effecte
15c50 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 d by the sqlite3
15c60 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a _interrupt()..**
15c70 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ^A call to sqli
15c80 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 te3_interrupt(D)
15c90 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 that occurs whe
15ca0 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 n there are no r
15cb0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 unning.** SQL st
15cc0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f atements is a no
15cd0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 -op and has no e
15ce0 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 ffect on SQL sta
15cf0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
15d00 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
15d10 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e r the sqlite3_in
15d20 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 terrupt() call r
15d30 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 eturns..**.** If
15d40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
15d50 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 nnection closes
15d60 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 while [sqlite3_i
15d70 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 nterrupt()].** i
15d80 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 s running then b
15d90 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c ad things will l
15da0 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f ikely happen..*/
15db0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e .void sqlite3_in
15dc0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a terrupt(sqlite3*
15dd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
15de0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 EF: Determine If
15df0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
15e00 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a t Is Complete.**
15e10 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
15e20 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 es are useful du
15e30 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e ring command-lin
15e40 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 e input to deter
15e50 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 mine if the.** c
15e60 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 urrently entered
15e70 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 text seems to f
15e80 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 orm a complete S
15e90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a QL statement or.
15ea0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c ** if additional
15eb0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 input is needed
15ec0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 before sending
15ed0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a the text into.**
15ee0 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 SQLite for pars
15ef0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 ing. ^These rou
15f00 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 tines return 1 i
15f10 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 f the input stri
15f20 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f ng.** appears to
15f30 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 be a complete S
15f40 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e QL statement. ^
15f50 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a A statement is j
15f60 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 udged to be.** c
15f70 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e omplete if it en
15f80 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f ds with a semico
15f90 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 lon token and is
15fa0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 not a prefix of
15fb0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 a.** well-forme
15fc0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 d CREATE TRIGGER
15fd0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 statement. ^Se
15fe0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 micolons that ar
15ff0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 e embedded withi
16000 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 n.** string lite
16010 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 rals or quoted i
16020 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 dentifier names
16030 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 or comments are
16040 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 not.** independe
16050 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 nt tokens (they
16060 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 are part of the
16070 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 token in which t
16080 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 hey are.** embed
16090 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f ded) and thus do
160a0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 not count as a
160b0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e statement termin
160c0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 ator. ^Whitespa
160d0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e ce.** and commen
160e0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 ts that follow t
160f0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c he final semicol
16100 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a on are ignored..
16110 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
16120 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 tines return 0 i
16130 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
16140 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 is incomplete.
16150 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ^If a.** memory
16160 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 allocation fails
16170 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f , then SQLITE_NO
16180 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e MEM is returned.
16190 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
161a0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 utines do not pa
161b0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 rse the SQL stat
161c0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 ements thus.** w
161d0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 ill not detect s
161e0 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 yntactically inc
161f0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a orrect SQL..**.*
16200 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 * ^(If SQLite ha
16210 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 s not been initi
16220 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 alized using [sq
16230 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
16240 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f ()] prior .** to
16250 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 invoking sqlite
16260 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 3_complete16() t
16270 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 hen sqlite3_init
16280 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f ialize() is invo
16290 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 ked.** automatic
162a0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f ally by sqlite3_
162b0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 complete16(). I
162c0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a f that initializ
162d0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 ation fails,.**
162e0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 then the return
162f0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 value from sqlit
16300 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 e3_complete16()
16310 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f will be non-zero
16320 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f .** regardless o
16330 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
16340 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 the input SQL i
16350 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a s complete.)^.**
16360 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f .** The input to
16370 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
16380 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 te()] must be a
16390 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
163a0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e ** UTF-8 string.
163b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 .**.** The input
163c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d to [sqlite3_com
163d0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 plete16()] must
163e0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e be a zero-termin
163f0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 ated.** UTF-16 s
16400 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 tring in native
16410 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 byte order..*/.i
16420 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c nt sqlite3_compl
16430 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a ete(const char *
16440 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 sql);.int sqlite
16450 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 3_complete16(con
16460 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a st void *sql);..
16470 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
16480 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 Register A Callb
16490 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 ack To Handle SQ
164a0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 LITE_BUSY Errors
164b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
164c0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c tine sets a call
164d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 back function th
164e0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f at might be invo
164f0 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 ked whenever.**
16500 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 an attempt is ma
16510 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 de to open a dat
16520 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 abase table that
16530 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a another thread.
16540 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 ** or process ha
16550 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 s locked..**.**
16560 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c ^If the busy cal
16570 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 lback is NULL, t
16580 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 hen [SQLITE_BUSY
16590 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
165a0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 RR_BLOCKED].** i
165b0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
165c0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f iately upon enco
165d0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 untering the loc
165e0 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 k. ^If the busy
165f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
16600 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 not NULL, then t
16610 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 he callback migh
16620 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 t be invoked wit
16630 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e h two arguments.
16640 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
16650 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
16660 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 e busy handler i
16670 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
16680 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 void* pointer wh
16690 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 ich.** is the th
166a0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
166b0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
166c0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 dler(). ^The se
166d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
166e0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e .** the busy han
166f0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 dler callback is
16700 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 the number of t
16710 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 imes that the bu
16720 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a sy handler has.*
16730 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 * been invoked f
16740 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 or this locking
16750 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a event. ^If the.
16760 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b ** busy callback
16770 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e returns 0, then
16780 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 no additional a
16790 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 ttempts are made
167a0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 to.** access th
167b0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b e database and [
167c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 SQLITE_BUSY] or
167d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
167e0 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e OCKED] is return
167f0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 ed..** ^If the c
16800 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
16810 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 non-zero, then a
16820 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a nother attempt.*
16830 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 * is made to ope
16840 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
16850 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 or reading and t
16860 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 he cycle repeats
16870 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 ..**.** The pres
16880 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 ence of a busy h
16890 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 andler does not
168a0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 guarantee that i
168b0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 t will be invoke
168c0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 d.** when there
168d0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 is lock contenti
168e0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 on. ^If SQLite d
168f0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 etermines that i
16900 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 nvoking the busy
16910 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c .** handler coul
16920 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 d result in a de
16930 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 adlock, it will
16940 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 go ahead and ret
16950 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
16960 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ].** or [SQLITE_
16970 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 IOERR_BLOCKED] i
16980 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 nstead of invoki
16990 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ng the busy hand
169a0 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 ler..** Consider
169b0 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 a scenario wher
169c0 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 e one process is
169d0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 holding a read
169e0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 lock that.** it
169f0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f is trying to pro
16a00 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 mote to a reserv
16a10 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 ed lock and.** a
16a20 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
16a30 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 is holding a res
16a40 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 erved lock that
16a50 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 it is trying.**
16a60 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e to promote to an
16a70 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e exclusive lock.
16a80 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 The first proc
16a90 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 ess cannot proce
16aa0 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 ed.** because it
16ab0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 is blocked by t
16ac0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
16ad0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 e second process
16ae0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 cannot.** proce
16af0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 ed because it is
16b00 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 blocked by the
16b10 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 first. If both
16b20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 processes.** inv
16b30 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e oke the busy han
16b40 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 dlers, neither w
16b50 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f ill make any pro
16b60 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 gress. Therefor
16b70 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 e,.** SQLite ret
16b80 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 urns [SQLITE_BUS
16b90 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 Y] for the first
16ba0 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 process, hoping
16bb0 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 that this.** wi
16bc0 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 ll induce the fi
16bd0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 rst process to r
16be0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 elease its read
16bf0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a lock and allow.*
16c00 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f * the second pro
16c10 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e cess to proceed.
16c20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 .**.** ^The defa
16c30 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 ult busy callbac
16c40 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a k is NULL..**.**
16c50 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 ^The [SQLITE_BU
16c60 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e SY] error is con
16c70 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 verted to [SQLIT
16c80 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
16c90 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 .** when SQLite
16ca0 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 is in the middle
16cb0 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e of a large tran
16cc0 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c saction where al
16cd0 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 l the.** changes
16ce0 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e will not fit in
16cf0 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 to the in-memory
16d00 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 cache. SQLite
16d10 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 will.** already
16d20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 hold a RESERVED
16d30 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 lock on the data
16d40 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 base file, but i
16d50 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 t needs.** to pr
16d60 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 omote this lock
16d70 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 to EXCLUSIVE so
16d80 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c that it can spil
16d90 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 l cache.** pages
16da0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 into the databa
16db0 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 se file without
16dc0 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 harm to concurre
16dd0 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 nt.** readers.
16de0 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 ^If it is unable
16df0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 to promote the
16e00 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 lock, then the i
16e10 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 n-memory.** cach
16e20 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 e will be left i
16e30 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e n an inconsisten
16e40 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 t state and so t
16e50 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 he error.** code
16e60 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f is promoted fro
16e70 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 m the relatively
16e80 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f benign [SQLITE_
16e90 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 BUSY] to.** the
16ea0 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c more severe [SQL
16eb0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
16ec0 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 D]. ^This error
16ed0 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a code promotion.
16ee0 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 ** forces an aut
16ef0 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 omatic rollback
16f00 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 of the changes.
16f10 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 See the.** <a h
16f20 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 ref="/cvstrac/wi
16f30 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 ki?p=CorruptionF
16f40 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f ollowingBusyErro
16f50 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f r">.** Corruptio
16f60 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 nFollowingBusyEr
16f70 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 ror</a> wiki pag
16f80 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 e for a discussi
16f90 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 on of why.** thi
16fa0 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a s is important..
16fb0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 **.** ^(There ca
16fc0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 n only be a sing
16fd0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 le busy handler
16fe0 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 defined for each
16ff0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
17000 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 nnection]. Sett
17010 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 ing a new busy h
17020 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e andler clears an
17030 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 y.** previously
17040 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 set handler.)^
17050 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 ^Note that calli
17060 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ng [sqlite3_busy
17070 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 _timeout()].** w
17080 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 ill also set or
17090 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 clear the busy h
170a0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 andler..**.** Th
170b0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 e busy callback
170c0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 should not take
170d0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 any actions whic
170e0 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 h modify the.**
170f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17100 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
17110 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
17120 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 r. Any such act
17130 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 ions.** result i
17140 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
17150 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 vior..** .** A b
17160 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 usy handler must
17170 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 not close the d
17180 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
17190 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 on.** or [prepar
171a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
171b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
171c0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a usy handler..*/.
171d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 int sqlite3_busy
171e0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
171f0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
17200 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
17210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
17220 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
17230 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f t.**.** ^This ro
17240 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 utine sets a [sq
17250 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
17260 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 er | busy handle
17270 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a r] that sleeps.*
17280 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 * for a specifie
17290 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 d amount of time
172a0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 when a table is
172b0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 locked. ^The h
172c0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
172d0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
172e0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
172f0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
17300 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
17310 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
17320 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 ated. ^After at
17330 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c least "ms" mill
17340 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
17350 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e ping,.** the han
17360 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 dler returns 0 w
17370 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c hich causes [sql
17380 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 ite3_step()] to
17390 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
173a0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 E_BUSY] or [SQLI
173b0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
173c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e ]..**.** ^Callin
173d0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 g this routine w
173e0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 ith an argument
173f0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 less than or equ
17400 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 al to zero.** tu
17410 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 rns off all busy
17420 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a handlers..**.**
17430 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ^(There can onl
17440 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
17450 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 sy handler for a
17460 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b particular.** [
17470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17480 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 ion] any any giv
17490 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 en moment. If a
174a0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 nother busy hand
174b0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e ler.** was defin
174c0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 ed (using [sqli
174d0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
174e0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 ()]) prior to ca
174f0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f lling.** this ro
17500 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 utine, that othe
17510 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 r busy handler i
17520 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a s cleared.)^.*/.
17530 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 int sqlite3_busy
17540 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 _timeout(sqlite3
17550 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a *, int ms);../*.
17560 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
17570 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 venience Routine
17580 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 s For Running Qu
17590 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 eries.**.** This
175a0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 is a legacy int
175b0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 erface that is p
175c0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 reserved for bac
175d0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
175e0 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 lity..** Use of
175f0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 this interface i
17600 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 s not recommende
17610 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 d..**.** Definit
17620 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 ion: A <b>result
17630 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 table</b> is me
17640 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 mory data struct
17650 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 ure created by t
17660 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 he.** [sqlite3_g
17670 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 et_table()] inte
17680 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 rface. A result
17690 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 table records t
176a0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 he.** complete q
176b0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f uery results fro
176c0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 m one or more qu
176d0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eries..**.** The
176e0 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 table conceptua
176f0 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 lly has a number
17700 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c of rows and col
17710 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 umns. But.** th
17720 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 ese numbers are
17730 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 not part of the
17740 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 result table its
17750 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e elf. These.** n
17760 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 umbers are obtai
17770 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 ned separately.
17780 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 Let N be the nu
17790 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 mber of rows.**
177a0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d and M be the num
177b0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a ber of columns..
177c0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
177d0 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 able is an array
177e0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 of pointers to
177f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
17800 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a UTF-8 strings..*
17810 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 * There are (N+1
17820 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 )*M elements in
17830 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 the array. The
17840 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 first M pointers
17850 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 point.** to zer
17860 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
17870 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 ings that conta
17880 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 in the names of
17890 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 the columns..**
178a0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e The remaining en
178b0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 tries all point
178c0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 to query results
178d0 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 . NULL values r
178e0 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c esult.** in NULL
178f0 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 pointers. All
17900 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 other values are
17910 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 in their UTF-8
17920 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
17930 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 ** string repres
17940 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 entation as retu
17950 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
17960 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e _column_text()].
17970 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 .**.** A result
17980 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 table might cons
17990 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f ist of one or mo
179a0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 re memory alloca
179b0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 tions..** It is
179c0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 not safe to pass
179d0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 a result table
179e0 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c directly to [sql
179f0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
17a00 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
17a10 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f should be deallo
17a20 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c cated using [sql
17a30 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
17a40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 )]..**.** ^(As a
17a50 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 n example of the
17a60 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f result table fo
17a70 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 rmat, suppose a
17a80 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 query result.**
17a90 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a is as follows:.*
17aa0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
17ab0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
17ac0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 Name | A
17ad0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d ge.** ---
17ae0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
17af0 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 ----.** A
17b00 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a lice | 43.
17b10 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 ** Bob
17b20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 | 28.**
17b30 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 Cindy
17b40 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c | 21.** </pre><
17b50 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
17b60 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f ** There are two
17b70 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 column (M==2) a
17b80 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e nd three rows (N
17b90 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a ==3). Thus the.
17ba0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 ** result table
17bb0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 has 8 entries.
17bc0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 Suppose the resu
17bd0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 lt table is stor
17be0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 ed.** in an arra
17bf0 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 y names azResult
17c00 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 . Then azResult
17c10 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 holds this cont
17c20 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ent:.**.** <bloc
17c30 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
17c40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
17c50 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b #91;0] = "Name";
17c60 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
17c70 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 ult[1] = "Ag
17c80 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
17c90 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 Result[2] =
17ca0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 "Alice";.**
17cb0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
17cc0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 3] = "43";.**
17cd0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
17ce0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 1;4] = "Bob";.**
17cf0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
17d00 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a [5] = "28";.
17d10 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
17d20 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e lt[6] = "Cin
17d30 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 dy";.** a
17d40 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d zResult[7] =
17d50 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e "21";.** </pre>
17d60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
17d70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
17d80 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 e3_get_table() f
17d90 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 unction evaluate
17da0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a s one or more.**
17db0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 semicolon-separ
17dc0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 ated SQL stateme
17dd0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d nts in the zero-
17de0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
17df0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 .** string of it
17e00 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 s 2nd parameter
17e10 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 and returns a re
17e20 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 sult table to th
17e30 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 e.** pointer giv
17e40 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 en in its 3rd pa
17e50 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 rameter..**.** A
17e60 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 fter the applica
17e70 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 tion has finishe
17e80 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c d with the resul
17e90 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 t from sqlite3_g
17ea0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 et_table(),.** i
17eb0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 t must pass the
17ec0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 result table poi
17ed0 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f nter to sqlite3_
17ee0 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 free_table() in
17ef0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 order to.** rele
17f00 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 ase the memory t
17f10 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 hat was malloced
17f20 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 . Because of th
17f30 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 e way the.** [sq
17f40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
17f50 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 happens within s
17f60 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
17f70 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a (), the calling.
17f80 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ** function must
17f90 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c not try to call
17fa0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
17fb0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c ] directly. Onl
17fc0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 y.** [sqlite3_fr
17fd0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 ee_table()] is a
17fe0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 ble to release t
17ff0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 he memory proper
18000 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a ly and safely..*
18010 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
18020 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 _get_table() int
18030 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d erface is implem
18040 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 ented as a wrapp
18050 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 er around.** [sq
18060 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 lite3_exec()].
18070 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
18080 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 table() routine
18090 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 does not have ac
180a0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 cess.** to any i
180b0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 nternal data str
180c0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 uctures of SQLit
180d0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 e. It uses only
180e0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 the public.** i
180f0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 nterface defined
18100 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e here. As a con
18110 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 sequence, errors
18120 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 that occur in t
18130 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 he.** wrapper la
18140 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 yer outside of t
18150 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c he internal [sql
18160 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c ite3_exec()] cal
18170 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 l are not.** ref
18180 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 lected in subseq
18190 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
181a0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
181b0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
181c0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 _errmsg()]..*/.i
181d0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 nt sqlite3_get_t
181e0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 able(. sqlite3
181f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a *db, /*
18200 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
18210 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
18220 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 r *zSql, /*
18230 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 SQL to be evalua
18240 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ted */. char **
18250 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f *pazResult, /
18260 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 * Results of the
18270 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 query */. int
18280 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 *pnRow,
18290 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
182a0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 esult rows writt
182b0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 en here */. int
182c0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 *pnColumn,
182d0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
182e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 result columns w
182f0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
18300 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 char **pzErrmsg
18310 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 /* Error
18320 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 msg written here
18330 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 */.);.void sqli
18340 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 te3_free_table(c
18350 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a har **result);..
18360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18370 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 Formatted String
18380 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 Printing Functi
18390 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
183a0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 routines are wor
183b0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 k-alikes of the
183c0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c "printf()" famil
183d0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a y of functions.*
183e0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 * from the stand
183f0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
18400 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
18410 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
18420 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
18430 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
18440 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
18450 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
18460 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
18470 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
18480 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
18490 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
184a0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
184b0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
184c0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
184d0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 _free()]. ^Both
184e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
184f0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
18500 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d er if [sqlite3_m
18510 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 alloc()] is unab
18520 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 le to allocate e
18530 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 nough.** memory
18540 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 to hold the resu
18550 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a lting string..**
18560 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 .** ^(The sqlite
18570 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 3_snprintf() rou
18580 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 tine is similar
18590 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 to "snprintf()"
185a0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e from.** the stan
185b0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 dard C library.
185c0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 The result is w
185d0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a ritten into the.
185e0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 ** buffer suppli
185f0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
18600 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 parameter whose
18610 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 size is given b
18620 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 y.** the first p
18630 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 arameter. Note t
18640 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 hat the order of
18650 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 the.** first tw
18660 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 o parameters is
18670 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e reversed from sn
18680 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 printf().)^ Thi
18690 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f s is an.** histo
186a0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 rical accident t
186b0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 hat cannot be fi
186c0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 xed without brea
186d0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 king.** backward
186e0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
186f0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 ^(Note also th
18700 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 at sqlite3_snpri
18710 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 ntf().** returns
18720 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 a pointer to it
18730 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 s buffer instead
18740 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
18750 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 f.** characters
18760 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e actually written
18770 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 into the buffer
18780 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 .)^ We admit th
18790 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 at.** the number
187a0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 of characters w
187b0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 ritten would be
187c0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 a more useful re
187d0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 turn.** value bu
187e0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e t we cannot chan
187f0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ge the implement
18800 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
18810 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e _snprintf().** n
18820 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ow without break
18830 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 ing compatibilit
18840 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e y..**.** ^As lon
18850 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 g as the buffer
18860 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 size is greater
18870 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 than zero, sqlit
18880 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
18890 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
188a0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 the buffer is a
188b0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 lways zero-termi
188c0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 nated. ^The fir
188d0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 st.** parameter
188e0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c "n" is the total
188f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
18900 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 fer, including s
18910 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 pace for.** the
18920 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
18930 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 So the longest
18940 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e string that can
18950 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a be completely.*
18960 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 * written will b
18970 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 e n-1 characters
18980 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
18990 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 ite3_vsnprintf()
189a0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 routine is a va
189b0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 rargs version of
189c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
189d0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 f()..**.** These
189e0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d routines all im
189f0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 plement some add
18a00 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 itional formatti
18a10 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 ng.** options th
18a20 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f at are useful fo
18a30 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 r constructing S
18a40 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
18a50 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 * All of the usu
18a60 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d al printf() form
18a70 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 atting options a
18a80 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 pply. In additi
18a90 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 on, there.** is
18aa0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 are "%q", "%Q",
18ab0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 and "%z" options
18ac0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 ..**.** ^(The %q
18ad0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
18ae0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 ke %s in that it
18af0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e substitutes a n
18b00 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ul-terminated.**
18b10 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
18b20 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
18b30 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
18b40 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
18b50 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
18b60 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
18b70 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
18b80 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 ring literal.)^
18b90 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 By doubling eac
18ba0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 h '\''.** charac
18bb0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 ter it escapes t
18bc0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e hat character an
18bd0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 d allows it to b
18be0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a e inserted into.
18bf0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a ** the string..*
18c00 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
18c10 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 , assume the str
18c20 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 ing variable zTe
18c30 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 xt contains text
18c40 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
18c50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
18c60 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
18c70 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 Text = "It's a h
18c80 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c appy day!";.** <
18c90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
18ca0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e e>.**.** One can
18cb0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 use this text i
18cc0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
18cd0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a nt as follows:.*
18ce0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
18cf0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
18d00 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
18d10 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
18d20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
18d30 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 S('%q')", zText)
18d40 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
18d50 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
18d60 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
18d70 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
18d80 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
18d90 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 uote>.**.** Beca
18da0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 use the %q forma
18db0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 t string is used
18dc0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 , the '\'' chara
18dd0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a cter in zText.**
18de0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 is escaped and
18df0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 the SQL generate
18e00 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a d is as follows:
18e10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
18e20 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
18e30 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
18e40 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 VALUES('It''s a
18e50 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 happy day!').**
18e60 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
18e70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te>.**.** This i
18e80 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 s correct. Had
18e90 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 we used %s inste
18ea0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 ad of %q, the ge
18eb0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 nerated SQL.** w
18ec0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 ould have looked
18ed0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
18ee0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
18ef0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
18f00 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
18f10 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 S('It's a happy
18f20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 day!');.** </pre
18f30 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
18f40 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 *.** This second
18f50 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 example is an S
18f60 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e QL syntax error.
18f70 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 As a general r
18f80 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a ule you should.*
18f90 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 * always use %q
18fa0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 instead of %s wh
18fb0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 en inserting tex
18fc0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 t into a string
18fd0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e literal..**.** ^
18fe0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 (The %Q option w
18ff0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 orks like %q exc
19000 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 ept it also adds
19010 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 single quotes a
19020 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 round.** the out
19030 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 side of the tota
19040 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 l string. Addit
19050 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 ionally, if the
19060 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
19070 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 .** argument lis
19080 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
19090 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 ter, %Q substitu
190a0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 tes the text "NU
190b0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 LL" (without.**
190c0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 single quotes).)
190d0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 ^ So, for examp
190e0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 le, one could sa
190f0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 y:.**.** <blockq
19100 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
19110 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
19120 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
19130 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
19140 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 ALUES(%Q)", zTex
19150 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f t);.** sqlite3_
19160 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 exec(db, zSQL, 0
19170 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c , 0, 0);.** sql
19180 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b ite3_free(zSQL);
19190 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
191a0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
191b0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c e code above wil
191c0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 l render a corre
191d0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ct SQL statement
191e0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 in the zSQL.**
191f0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 variable even if
19200 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 the zText varia
19210 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ble is a NULL po
19220 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 inter..**.** ^(T
19230 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 he "%z" formatti
19240 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 ng option works
19250 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 like "%s" but wi
19260 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 th the.** additi
19270 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 on that after th
19280 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 e string has bee
19290 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 n read and copie
192a0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 d into.** the re
192b0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 sult, [sqlite3_f
192c0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 ree()] is called
192d0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 on the input st
192e0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 ring.)^.*/.char
192f0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 *sqlite3_mprintf
19300 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e (const char*,...
19310 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
19320 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 _vmprintf(const
19330 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
19340 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 .char *sqlite3_s
19350 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 nprintf(int,char
19360 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e *,const char*, .
19370 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 ..);.char *sqlit
19380 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 e3_vsnprintf(int
19390 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 ,char*,const cha
193a0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f r*, va_list);../
193b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
193c0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e emory Allocation
193d0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a Subsystem.**.**
193e0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
193f0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 uses these thre
19400 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 e routines for a
19410 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a ll of its own.**
19420 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 internal memory
19430 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
19440 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 s. "Core" in the
19450 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e previous senten
19460 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 ce.** does not i
19470 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 nclude operating
19480 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 -system specific
19490 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
194a0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e ion. The.** Win
194b0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 dows VFS uses na
194c0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e tive malloc() an
194d0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d d free() for som
194e0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a e operations..**
194f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
19500 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e _malloc() routin
19510 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
19520 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a ter to a block.*
19530 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c * of memory at l
19540 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
19550 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 length, where N
19560 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 is the parameter
19570 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
19580 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 _malloc() is una
19590 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 ble to obtain su
195a0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a fficient free.**
195b0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 memory, it retu
195c0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
195d0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 er. ^If the par
195e0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 ameter N to.** s
195f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
19600 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 is zero or negat
19610 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ive then sqlite3
19620 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e _malloc() return
19630 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s.** a NULL poin
19640 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c ter..**.** ^Call
19650 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ing sqlite3_free
19660 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 () with a pointe
19670 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 r previously ret
19680 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 urned.** by sqli
19690 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 te3_malloc() or
196a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
196b0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 ) releases that
196c0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 memory so.** tha
196d0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 t it might be re
196e0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 used. ^The sqli
196f0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 te3_free() routi
19700 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 ne is.** a no-op
19710 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 if is called wi
19720 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
19730 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 r. Passing a NU
19740 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f LL pointer.** to
19750 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
19760 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 is harmless. Af
19770 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c ter being freed,
19780 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c memory.** shoul
19790 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 d neither be rea
197a0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 d nor written.
197b0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 Even reading pre
197c0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a viously freed.**
197d0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 memory might re
197e0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e sult in a segmen
197f0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 tation fault or
19800 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 other severe err
19810 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f or..** Memory co
19820 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d rruption, a segm
19830 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 entation fault,
19840 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 or other severe
19850 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 error.** might r
19860 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 esult if sqlite3
19870 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 _free() is calle
19880 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c d with a non-NUL
19890 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a L pointer that.*
198a0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e * was not obtain
198b0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ed from sqlite3_
198c0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 malloc() or sqli
198d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a te3_realloc()..*
198e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 *.** ^(The sqlit
198f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 e3_realloc() int
19900 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
19910 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 to resize a.** p
19920 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f rior memory allo
19930 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 cation to be at
19940 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 least N bytes, w
19950 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a here N is the.**
19960 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
19970 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 r. The memory a
19980 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 llocation to be
19990 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 resized is the f
199a0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
199b0 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 r.)^ ^ If the fi
199c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
199d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
199e0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 ().** is a NULL
199f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
19a00 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
19a10 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
19a20 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
19a30 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 loc(N) where N i
19a40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
19a50 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
19a60 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 3_realloc()..**
19a70 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 ^If the second p
19a80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
19a90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 te3_realloc() is
19aa0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 zero or.** nega
19ab0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 tive then the be
19ac0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c havior is exactl
19ad0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 y the same as ca
19ae0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 lling.** sqlite3
19af0 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 _free(P) where P
19b00 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 is the first pa
19b10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
19b20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
19b30 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f ^sqlite3_reallo
19b40 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f c() returns a po
19b50 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 inter to a memor
19b60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
19b70 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 of at least N by
19b80 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e tes in size or N
19b90 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e ULL if sufficien
19ba0 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 t memory is unav
19bb0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 ailable..** ^If
19bc0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 M is the size of
19bd0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
19be0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 ation, then min(
19bf0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 N,M) bytes.** of
19c00 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
19c10 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 ation are copied
19c20 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e into the beginn
19c30 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 ing of buffer re
19c40 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
19c50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 ite3_realloc() a
19c60 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c nd the prior all
19c70 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 ocation is freed
19c80 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
19c90 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 _realloc() retur
19ca0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ns NULL, then th
19cb0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
19cc0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 on.** is not fre
19cd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d ed..**.** ^The m
19ce0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 emory returned b
19cf0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
19d00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
19d10 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 ealloc().** is a
19d20 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f lways aligned to
19d30 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 at least an 8 b
19d40 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 yte boundary, or
19d50 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 to a.** 4 byte
19d60 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 boundary if the
19d70 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 [SQLITE_4_BYTE_A
19d80 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 LIGNED_MALLOC] c
19d90 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
19da0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a ption is used..*
19db0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 *.** In SQLite v
19dc0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 ersion 3.5.0 and
19dd0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 3.5.1, it was p
19de0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e ossible to defin
19df0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f e.** the SQLITE_
19e00 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f OMIT_MEMORY_ALLO
19e10 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 CATION which wou
19e20 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 ld cause the bui
19e30 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 lt-in.** impleme
19e40 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 ntation of these
19e50 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
19e60 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 omitted. That c
19e70 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
19e80 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 no longer provid
19e90 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d ed. Only built-
19ea0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
19eb0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 tors can be used
19ec0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 ..**.** The Wind
19ed0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 ows OS interface
19ee0 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 layer calls.**
19ef0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f the system mallo
19f00 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 c() and free() d
19f10 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e irectly when con
19f20 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e verting.** filen
19f30 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 ames between the
19f40 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 UTF-8 encoding
19f50 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a used by SQLite.*
19f60 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 * and whatever f
19f70 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 ilename encoding
19f80 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 is used by the
19f90 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f particular Windo
19fa0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 ws.** installati
19fb0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f on. Memory allo
19fc0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 cation errors ar
19fd0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a e detected, but.
19fe0 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f ** they are repo
19ff0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 rted back as [SQ
1a000 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f LITE_CANTOPEN] o
1a010 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 r.** [SQLITE_IOE
1a020 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 RR] rather than
1a030 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a [SQLITE_NOMEM]..
1a040 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 **.** The pointe
1a050 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b r arguments to [
1a060 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1a070 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
1a080 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 lloc()].** must
1a090 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f be either NULL o
1a0a0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 r else pointers
1a0b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 obtained from a
1a0c0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 prior.** invocat
1a0d0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
1a0e0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 malloc()] or [sq
1a0f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
1a100 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f that have.** no
1a110 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 t yet been relea
1a120 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 sed..**.** The a
1a130 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
1a140 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 not read or writ
1a150 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a e any part of.**
1a160 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f a block of memo
1a170 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 ry after it has
1a180 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 been released us
1a190 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
1a1a0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 free()] or [sqli
1a1b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a te3_realloc()]..
1a1c0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
1a1d0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f _malloc(int);.vo
1a1e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c id *sqlite3_real
1a1f0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b loc(void*, int);
1a200 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 .void sqlite3_fr
1a210 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ee(void*);../*.*
1a220 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
1a230 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 ry Allocator Sta
1a240 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 tistics.**.** SQ
1a250 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 Lite provides th
1a260 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 ese two interfac
1a270 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 es for reporting
1a280 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a on the status.*
1a290 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
1a2a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 3_malloc()], [sq
1a2b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 lite3_free()], a
1a2c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c nd [sqlite3_real
1a2d0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e loc()].** routin
1a2e0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 es, which form t
1a2f0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f he built-in memo
1a300 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
1a310 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e bsystem..**.** ^
1a320 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
1a330 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 ory_used()] rout
1a340 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
1a350 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a number of bytes.
1a360 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 ** of memory cur
1a370 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 rently outstandi
1a380 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 ng (malloced but
1a390 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 not freed)..**
1a3a0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 ^The [sqlite3_me
1a3b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
1a3c0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
1a3d0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a s the maximum.**
1a3e0 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 value of [sqlit
1a3f0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
1a400 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 ] since the high
1a410 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 -water mark.** w
1a420 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 as last reset.
1a430 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 ^The values retu
1a440 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
1a450 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
1a460 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
1a470 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
1a480 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 ()] include any
1a490 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 overhead.** adde
1a4a0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 d by SQLite in i
1a4b0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ts implementatio
1a4c0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 n of [sqlite3_ma
1a4d0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 lloc()],.** but
1a4e0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 not overhead add
1a4f0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e ed by the any un
1a500 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 derlying system
1a510 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 library.** routi
1a520 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 nes that [sqlite
1a530 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 3_malloc()] may
1a540 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 call..**.** ^The
1a550 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 memory high-wat
1a560 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 er mark is reset
1a570 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 to the current
1a580 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c value of.** [sql
1a590 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
1a5a0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 ()] if and only
1a5b0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
1a5c0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
1a5d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
1a5e0 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 ()] is true. ^T
1a5f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
1a600 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 d.** by [sqlite3
1a610 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
1a620 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 r(1)] is the hig
1a630 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 h-water mark.**
1a640 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 prior to the res
1a650 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 et..*/.sqlite3_i
1a660 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d nt64 sqlite3_mem
1a670 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a ory_used(void);.
1a680 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
1a690 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
1a6a0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 hwater(int reset
1a6b0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Flag);../*.** CA
1a6c0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 PI3REF: Pseudo-R
1a6d0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e andom Number Gen
1a6e0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c erator.**.** SQL
1a6f0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 ite contains a h
1a700 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 igh-quality pseu
1a710 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 do-random number
1a720 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 generator (PRNG
1a730 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c ) used to.** sel
1a740 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 ect random [ROWI
1a750 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e D | ROWIDs] when
1a760 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 inserting new r
1a770 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 ecords into a ta
1a780 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 ble that.** alre
1a790 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 ady uses the lar
1a7a0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 gest possible [R
1a7b0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 OWID]. The PRNG
1a7c0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f is also used fo
1a7d0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 r.** the build-i
1a7e0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 n random() and r
1a7f0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 andomblob() SQL
1a800 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 functions. This
1a810 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 interface allow
1a820 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e s.** application
1a830 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
1a840 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 same PRNG for ot
1a850 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a her purposes..**
1a860 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 .** ^A call to t
1a870 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 his routine stor
1a880 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 es N bytes of ra
1a890 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 ndomness into bu
1a8a0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ffer P..**.** ^T
1a8b0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 he first time th
1a8c0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e is routine is in
1a8d0 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e voked (either in
1a8e0 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a ternally or by.*
1a8f0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
1a900 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 n) the PRNG is s
1a910 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 eeded using rand
1a920 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a omness obtained.
1a930 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e ** from the xRan
1a940 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f domness method o
1a950 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 f the default [s
1a960 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
1a970 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 ct..** ^On all s
1a980 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 ubsequent invoca
1a990 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 tions, the pseud
1a9a0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 o-randomness is
1a9b0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 generated.** int
1a9c0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 ernally and with
1a9d0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 out recourse to
1a9e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
1a9f0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a ] xRandomness.**
1aa00 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 method..*/.void
1aa10 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e sqlite3_randomn
1aa20 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 ess(int N, void
1aa30 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *P);../*.** CAPI
1aa40 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 3REF: Compile-Ti
1aa50 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e me Authorization
1aa60 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a Callbacks.**.**
1aa70 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 ^This routine r
1aa80 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 egisters an auth
1aa90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1aaa0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
1aab0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
1aac0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 onnection], supp
1aad0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 lied in the firs
1aae0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e t argument..** ^
1aaf0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
1ab00 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
1ab10 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d ed as SQL statem
1ab20 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 ents are being c
1ab30 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 ompiled.** by [s
1ab40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
1ab50 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
1ab60 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
1ab70 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 re_v2()],.** [sq
1ab80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
1ab90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1aba0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
1abb0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a ^At various.**
1abc0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 points during t
1abd0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 he compilation p
1abe0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 rocess, as logic
1abf0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 is being create
1ac00 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 d.** to perform
1ac10 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c various actions,
1ac20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1ac30 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
1ac40 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 ked to.** see if
1ac50 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 those actions a
1ac60 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 re allowed. ^Th
1ac70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1ac80 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 lback should.**
1ac90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
1aca0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 K] to allow the
1acb0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f action, [SQLITE_
1acc0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c IGNORE] to disal
1acd0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 low the.** speci
1ace0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 fic action but a
1acf0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 llow the SQL sta
1ad00 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e tement to contin
1ad10 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ue to be.** comp
1ad20 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 iled, or [SQLITE
1ad30 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 _DENY] to cause
1ad40 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 the entire SQL s
1ad50 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a tatement to be.*
1ad60 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 * rejected with
1ad70 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 an error. ^If t
1ad80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1ad90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a llback returns.*
1ada0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 * any value othe
1adb0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 r than [SQLITE_I
1adc0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f GNORE], [SQLITE_
1add0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OK], or [SQLITE_
1ade0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 DENY].** then th
1adf0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
1ae00 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
1ae10 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
1ae20 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 triggered.** th
1ae30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c e authorizer wil
1ae40 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
1ae50 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
1ae60 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c .** When the cal
1ae70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
1ae80 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 QLITE_OK], that
1ae90 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 means the operat
1aea0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 ion.** requested
1aeb0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 is ok. ^When t
1aec0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
1aed0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 rns [SQLITE_DENY
1aee0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ], the.** [sqlit
1aef0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1af00 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
1af10 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
1af20 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 ed the.** author
1af30 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
1af40 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
1af50 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 sage explaining
1af60 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 that.** access i
1af70 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a s denied. .**.**
1af80 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
1af90 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 meter to the aut
1afa0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1afb0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
1afc0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d e third.** param
1afd0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
1afe0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1aff0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 er() interface.
1b000 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
1b010 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 meter.** to the
1b020 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 callback is an i
1b030 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 nteger [SQLITE_C
1b040 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 OPY | action cod
1b050 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 e] that specifie
1b060 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 s.** the particu
1b070 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 lar action to be
1b080 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 authorized. ^Th
1b090 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 e third through
1b0a0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 sixth parameters
1b0b0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
1b0c0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 ack are zero-ter
1b0d0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
1b0e0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 that contain add
1b0f0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 itional.** detai
1b100 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 ls about the act
1b110 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
1b120 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ized..**.** ^If
1b130 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 the action code
1b140 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d is [SQLITE_READ]
1b150 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c .** and the call
1b160 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
1b170 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
1b180 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 n the.** [prepar
1b190 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 ed statement] st
1b1a0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 atement is const
1b1b0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 ructed to substi
1b1c0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 tute.** a NULL v
1b1d0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 alue in place of
1b1e0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d the table colum
1b1f0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 n that would hav
1b200 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 e.** been read i
1b210 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 f [SQLITE_OK] ha
1b220 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e d been returned.
1b230 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 The [SQLITE_IG
1b240 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 NORE].** return
1b250 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 can be used to d
1b260 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 eny an untrusted
1b270 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 user access to
1b280 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f individual.** co
1b290 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 lumns of a table
1b2a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 ..** ^If the act
1b2b0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c ion code is [SQL
1b2c0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 ITE_DELETE] and
1b2d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
1b2e0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urns.** [SQLITE_
1b2f0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 IGNORE] then the
1b300 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 [DELETE] operat
1b310 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 ion proceeds but
1b320 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 the.** [truncat
1b330 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 e optimization]
1b340 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 is disabled and
1b350 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c all rows are del
1b360 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c eted individuall
1b370 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 y..**.** An auth
1b380 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 orizer is used w
1b390 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hen [sqlite3_pre
1b3a0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 pare | preparing
1b3b0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 ].** SQL stateme
1b3c0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 nts from an untr
1b3d0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f usted source, to
1b3e0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
1b3f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
1b400 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f ** do not try to
1b410 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 access data the
1b420 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 y are not allowe
1b430 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 d to see, or tha
1b440 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a t they do not.**
1b450 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 try to execute
1b460 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d malicious statem
1b470 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 ents that damage
1b480 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 the database.
1b490 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
1b4a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d an application m
1b4b0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 ay allow a user
1b4c0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 to enter arbitra
1b4d0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 ry.** SQL querie
1b4e0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e s for evaluation
1b4f0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 by a database.
1b500 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 But the applica
1b510 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 tion does.** not
1b520 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 want the user t
1b530 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b o be able to mak
1b540 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e e arbitrary chan
1b550 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 ges to the.** da
1b560 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 tabase. An auth
1b570 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 orizer could the
1b580 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 n be put in plac
1b590 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 e while the.** u
1b5a0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 ser-entered SQL
1b5b0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 is being [sqlite
1b5c0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
1b5d0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 ared] that.** di
1b5e0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 sallows everythi
1b5f0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 ng except [SELEC
1b600 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a T] statements..*
1b610 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e *.** Application
1b620 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 s that need to p
1b630 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 rocess SQL from
1b640 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
1b650 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 s.** might also
1b660 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e consider lowerin
1b670 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 g resource limit
1b680 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 s using [sqlite3
1b690 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 _limit()].** and
1b6a0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 limiting databa
1b6b0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 se size using th
1b6c0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e e [max_page_coun
1b6d0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 t] [PRAGMA].** i
1b6e0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 n addition to us
1b6f0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 ing an authorize
1b700 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 r..**.** ^(Only
1b710 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 a single authori
1b720 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c zer can be in pl
1b730 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 ace on a databas
1b740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
1b750 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 at a time. Each
1b760 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
1b770 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
1b780 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a overrides the.**
1b790 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 previous call.)
1b7a0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 ^ ^Disable the
1b7b0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e authorizer by in
1b7c0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 stalling a NULL
1b7d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 callback..** The
1b7e0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 authorizer is d
1b7f0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
1b800 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 lt..**.** The au
1b810 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1b820 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
1b830 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
1b840 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
1b850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1b860 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
1b870 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1b880 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 allback..** Note
1b890 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
1b8a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
1b8b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1b8c0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
1b8d0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
1b8e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
1b8f0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
1b900 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
1b910 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
1b920 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f ^When [sqlite3_
1b930 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 prepare_v2()] is
1b940 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 used to prepare
1b950 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 a statement, th
1b960 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d e.** statement m
1b970 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 ight be re-prepa
1b980 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 red during [sqli
1b990 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 te3_step()] due
1b9a0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 to a .** schema
1b9b0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 change. Hence,
1b9c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
1b9d0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 should ensure th
1b9e0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 at the.** correc
1b9f0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c t authorizer cal
1ba00 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e lback remains in
1ba10 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 place during th
1ba20 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
1ba30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 )]..**.** ^Note
1ba40 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 that the authori
1ba50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
1ba60 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 invoked only dur
1ba70 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
1ba80 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 prepare()] or it
1ba90 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 s variants. Aut
1baa0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f horization is no
1bab0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 t.** performed d
1bac0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 uring statement
1bad0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 evaluation in [s
1bae0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
1baf0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 unless.** as sta
1bb00 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 ted in the previ
1bb10 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 ous paragraph, s
1bb20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e qlite3_step() in
1bb30 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 vokes.** sqlite3
1bb40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f _prepare_v2() to
1bb50 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 reprepare a sta
1bb60 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 tement after a s
1bb70 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f chema change..*/
1bb80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 .int sqlite3_set
1bb90 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 _authorizer(. s
1bba0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 qlite3*,. int (
1bbb0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e *xAuth)(void*,in
1bbc0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f t,const char*,co
1bbd0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
1bbe0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
1bbf0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 *),. void *pUse
1bc00 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 rData.);../*.**
1bc10 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 CAPI3REF: Author
1bc20 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 izer Return Code
1bc30 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c s.**.** The [sql
1bc40 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1bc50 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
1bc60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1bc70 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 on] must.** retu
1bc80 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 rn either [SQLIT
1bc90 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 E_OK] or one of
1bca0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 these two consta
1bcb0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 nts in order.**
1bcc0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 to signal SQLite
1bcd0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
1bce0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 the action is pe
1bcf0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 rmitted. See th
1bd00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 e.** [sqlite3_se
1bd10 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
1bd20 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 uthorizer docume
1bd30 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 ntation] for add
1bd40 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
1bd50 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f mation..**.** No
1bd60 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 te that SQLITE_I
1bd70 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 GNORE is also us
1bd80 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f ed as a [SQLITE_
1bd90 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 ROLLBACK | retur
1bda0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 n code].** from
1bdb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 the [sqlite3_vta
1bdc0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d b_on_conflict()]
1bdd0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 interface..*/.#
1bde0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
1bdf0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 NY 1 /* Abor
1be00 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
1be10 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f ent with an erro
1be20 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
1be30 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f ITE_IGNORE 2 /
1be40 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 * Don't allow ac
1be50 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 cess, but don't
1be60 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f generate an erro
1be70 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 r */../*.** CAPI
1be80 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 3REF: Authorizer
1be90 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a Action Codes.**
1bea0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
1beb0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1bec0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 )] interface reg
1bed0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
1bee0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 k function.** th
1bef0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f at is invoked to
1bf00 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 authorize certa
1bf10 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 in SQL statement
1bf20 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a actions. The.*
1bf30 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
1bf40 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 er to the callba
1bf50 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
1bf60 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 code that speci
1bf70 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 fies.** what act
1bf80 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 ion is being aut
1bf90 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 horized. These
1bfa0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 are the integer
1bfb0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 action codes tha
1bfc0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 t.** the authori
1bfd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 zer callback may
1bfe0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a be passed..**.*
1bff0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 * These action c
1c000 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 ode values signi
1c010 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 fy what kind of
1c020 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 operation is to
1c030 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 be.** authorized
1c040 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 . The 3rd and 4
1c050 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
1c060 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 the authorizati
1c070 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 on.** callback f
1c080 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 unction will be
1c090 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 parameters or NU
1c0a0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 LL depending on
1c0b0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a which of these.*
1c0c0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 * codes is used
1c0d0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
1c0e0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 rameter. ^(The
1c0f0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
1c100 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
1c110 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 er callback is t
1c120 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
1c130 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c atabase ("main",
1c140 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e "temp",.** etc.
1c150 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e ) if applicable.
1c160 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 )^ ^The 6th par
1c170 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
1c180 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1c190 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 k.** is the name
1c1a0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f of the inner-mo
1c1b0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 st trigger or vi
1c1c0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f ew that is respo
1c1d0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 nsible for.** th
1c1e0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 e access attempt
1c1f0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 or NULL if this
1c200 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
1c210 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d is directly from
1c220 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 .** top-level SQ
1c230 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a L code..*/./****
1c240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1c250 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1c260 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a ******* 3rd ****
1c270 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a ******** 4th ***
1c280 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e ********/.#defin
1c290 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1c2a0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 INDEX 1
1c2b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
1c2c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
1c2d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1c2e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
1c2f0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 ABLE 2
1c300 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1c310 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1c320 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1c330 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
1c340 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 MP_INDEX 3
1c350 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
1c360 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1c370 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1c380 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
1c390 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 P_TABLE 4
1c3a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1c3b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1c3c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1c3d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
1c3e0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f _TRIGGER 5 /
1c3f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
1c400 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1c410 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1c420 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
1c430 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a VIEW 6 /*
1c440 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
1c450 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1c460 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1c470 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 TE_CREATE_TRIGGE
1c480 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 R 7 /*
1c490 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
1c4a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1c4b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1c4c0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 E_CREATE_VIEW
1c4d0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 8 /* V
1c4e0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
1c4f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1c500 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1c510 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
1c520 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 9 /* Ta
1c530 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
1c540 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1c550 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1c560 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 DROP_INDEX
1c570 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 10 /* Ind
1c580 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
1c590 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1c5a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1c5b0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 ROP_TABLE
1c5c0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 11 /* Tabl
1c5d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1c5e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1c5f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1c600 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 OP_TEMP_INDEX
1c610 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 12 /* Index
1c620 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
1c630 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1c640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1c650 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 P_TEMP_TABLE
1c660 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 13 /* Table
1c670 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1c680 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1c690 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1c6a0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 _TEMP_TRIGGER
1c6b0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 14 /* Trigger
1c6c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
1c6d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1c6e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1c6f0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 TEMP_VIEW
1c700 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 15 /* View Nam
1c710 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
1c720 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1c730 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
1c740 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 RIGGER 1
1c750 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 6 /* Trigger N
1c760 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
1c770 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1c780 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 e SQLITE_DROP_VI
1c790 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 EW 17
1c7a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
1c7b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1c7c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1c7d0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 SQLITE_INSERT
1c7e0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 18
1c7f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1c800 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1c810 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1c820 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 SQLITE_PRAGMA
1c830 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 19
1c840 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 /* Pragma Name
1c850 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 1st arg or N
1c860 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ULL */.#define S
1c870 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 QLITE_READ
1c880 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 20
1c890 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1c8a0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
1c8b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1c8c0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 LITE_SELECT
1c8d0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 21 /
1c8e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
1c8f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1c900 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1c910 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 ITE_TRANSACTION
1c920 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 22 /*
1c930 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 Operation
1c940 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1c950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1c960 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 TE_UPDATE
1c970 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
1c980 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1c990 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
1c9a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1c9b0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 E_ATTACH
1c9c0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 24 /* F
1c9d0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e ilename N
1c9e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1c9f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1ca00 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 _DETACH
1ca10 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 25 /* Da
1ca20 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 tabase Name NU
1ca30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1ca40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ca50 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 ALTER_TABLE
1ca60 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 26 /* Dat
1ca70 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 abase Name Tab
1ca80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1ca90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
1caa0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 EINDEX
1cab0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 27 /* Inde
1cac0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c x Name NULL
1cad0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1cae0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e define SQLITE_AN
1caf0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 ALYZE
1cb00 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 28 /* Table
1cb10 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1cb20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1cb30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1cb40 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ATE_VTABLE
1cb50 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 29 /* Table
1cb60 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
1cb70 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1cb80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1cb90 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 _VTABLE
1cba0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 30 /* Table N
1cbb0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
1cbc0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
1cbd0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 ine SQLITE_FUNCT
1cbe0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 ION
1cbf0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 31 /* NULL
1cc00 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e Function
1cc10 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 Name */.#defi
1cc20 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f ne SQLITE_SAVEPO
1cc30 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 INT 3
1cc40 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
1cc50 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 Savepoint
1cc60 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
1cc70 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 e SQLITE_COPY
1cc80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
1cc90 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 /* No longer
1cca0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
1ccb0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 API3REF: Tracing
1ccc0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 And Profiling F
1ccd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 unctions.**.** T
1cce0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
1ccf0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 gister callback
1cd00 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 functions that c
1cd10 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a an be used for.*
1cd20 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 * tracing and pr
1cd30 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 ofiling the exec
1cd40 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 ution of SQL sta
1cd50 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e tements..**.** ^
1cd60 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
1cd70 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
1cd80 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 by sqlite3_trac
1cd90 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 e() is invoked a
1cda0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d t.** various tim
1cdb0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 es when an SQL s
1cdc0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e tatement is bein
1cdd0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 g run by [sqlite
1cde0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 3_step()]..** ^T
1cdf0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 he sqlite3_trace
1ce00 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 () callback is i
1ce10 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 nvoked with a UT
1ce20 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 F-8 rendering of
1ce30 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 the.** SQL stat
1ce40 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 ement text as th
1ce50 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 e statement firs
1ce60 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 t begins executi
1ce70 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f ng..** ^(Additio
1ce80 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 nal sqlite3_trac
1ce90 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 e() callbacks mi
1cea0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 ght occur.** as
1ceb0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 each triggered s
1cec0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 ubprogram is ent
1ced0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 ered. The callb
1cee0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 acks for trigger
1cef0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 s.** contain a U
1cf00 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 TF-8 SQL comment
1cf10 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 that identifies
1cf20 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a the trigger.)^.
1cf30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 **.** ^The callb
1cf40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
1cf50 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 istered by sqlit
1cf60 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 e3_profile() is
1cf70 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 invoked.** as ea
1cf80 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ch SQL statement
1cf90 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 finishes. ^The
1cfa0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 profile callbac
1cfb0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 k contains.** th
1cfc0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 e original state
1cfd0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e ment text and an
1cfe0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c estimate of wal
1cff0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 l-clock time.**
1d000 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 of how long that
1d010 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 statement took
1d020 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 to run. ^The pr
1d030 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a ofile callback.*
1d040 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 * time is in uni
1d050 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 ts of nanosecond
1d060 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 s, however the c
1d070 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 urrent implement
1d080 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 ation.** is only
1d090 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c capable of mill
1d0a0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 isecond resoluti
1d0b0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 on so the six le
1d0c0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a ast significant.
1d0d0 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 ** digits in the
1d0e0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e time are meanin
1d0f0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 gless. Future v
1d100 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
1d110 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 e.** might provi
1d120 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c de greater resol
1d130 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f ution on the pro
1d140 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 filer callback.
1d150 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The.** sqlite3_
1d160 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 profile() functi
1d170 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 on is considered
1d180 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e experimental an
1d190 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 d is.** subject
1d1a0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 to change in fut
1d1b0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
1d1c0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 SQLite..*/.void
1d1d0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 *sqlite3_trace(s
1d1e0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 qlite3*, void(*x
1d1f0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e Trace)(void*,con
1d200 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a st char*), void*
1d210 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 );.SQLITE_EXPERI
1d220 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c MENTAL void *sql
1d230 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c ite3_profile(sql
1d240 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a ite3*,. void(*
1d250 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c xProfile)(void*,
1d260 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 const char*,sqli
1d270 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 te3_uint64), voi
1d280 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1d290 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 3REF: Query Prog
1d2a0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a ress Callbacks.*
1d2b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1d2c0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
1d2d0 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 er(D,N,X,P) inte
1d2e0 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 rface causes the
1d2f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e callback.** fun
1d300 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e ction X to be in
1d310 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c voked periodical
1d320 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 ly during long r
1d330 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a unning calls to.
1d340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ** [sqlite3_exec
1d350 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
1d360 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ep()] and [sqlit
1d370 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 e3_get_table()]
1d380 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 for.** database
1d390 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 connection D. A
1d3a0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f n example use fo
1d3b0 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 r this.** interf
1d3c0 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 ace is to keep a
1d3d0 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 GUI updated dur
1d3e0 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 ing a large quer
1d3f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 y..**.** ^The pa
1d400 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 rameter P is pas
1d410 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 sed through as t
1d420 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
1d430 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c r to the .** cal
1d440 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 lback function X
1d450 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 . ^The paramete
1d460 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 r N is the numbe
1d470 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 r of .** [virtua
1d480 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 l machine instru
1d490 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 ctions] that are
1d4a0 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 evaluated betwe
1d4b0 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a en successive.**
1d4c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
1d4d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a the callback X..
1d4e0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 **.** ^Only a si
1d4f0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 ngle progress ha
1d500 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 ndler may be def
1d510 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 ined at one time
1d520 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 per.** [databas
1d530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 e connection]; s
1d540 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f etting a new pro
1d550 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 gress handler ca
1d560 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 ncels the.** old
1d570 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 one. ^Setting
1d580 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e parameter X to N
1d590 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 ULL disables the
1d5a0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
1d5b0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 r..** ^The progr
1d5c0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 ess handler is a
1d5d0 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 lso disabled by
1d5e0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 setting N to a v
1d5f0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 alue less.** tha
1d600 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 n 1..**.** ^If t
1d610 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
1d620 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
1d630 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 -zero, the opera
1d640 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 tion is.** inter
1d650 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 rupted. This fe
1d660 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 ature can be use
1d670 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
1d680 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 .** "Cancel" but
1d690 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f ton on a GUI pro
1d6a0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 gress dialog box
1d6b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 ..**.** The prog
1d6c0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c ress handler cal
1d6d0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
1d6e0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
1d6f0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
1d700 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1d710 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
1d720 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 ked the progress
1d730 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 handler..** Not
1d740 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
1d750 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
1d760 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
1d770 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
1d780 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
1d790 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
1d7a0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
1d7b0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
1d7c0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
1d7d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 /.void sqlite3_p
1d7e0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
1d7f0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 sqlite3*, int, i
1d800 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f nt(*)(void*), vo
1d810 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
1d820 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 I3REF: Opening A
1d830 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f New Database Co
1d840 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e nnection.**.** ^
1d850 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
1d860 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 pen an SQLite da
1d870 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 tabase file as s
1d880 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
1d890 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 .** filename arg
1d8a0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 ument. ^The file
1d8b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 name argument is
1d8c0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
1d8d0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c UTF-8 for.** sql
1d8e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
1d8f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1d900 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 ) and as UTF-16
1d910 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
1d920 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 te.** order for
1d930 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1d940 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 . ^(A [database
1d950 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
1d960 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a le is usually.**
1d970 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 returned in *pp
1d980 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 Db, even if an e
1d990 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 rror occurs. Th
1d9a0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e e only exception
1d9b0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 is that.** if S
1d9c0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 QLite is unable
1d9d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
1d9e0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b ry to hold the [
1d9f0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c sqlite3] object,
1da00 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 .** a NULL will
1da10 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 be written into
1da20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 *ppDb instead of
1da30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
1da40 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f e [sqlite3].** o
1da50 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 bject.)^ ^(If th
1da60 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
1da70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 ened (and/or cre
1da80 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c ated) successful
1da90 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c ly, then.** [SQL
1daa0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 ITE_OK] is retur
1dab0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 ned. Otherwise
1dac0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
1dad0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e is returned.)^ ^
1dae0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
1daf0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 errmsg()] or [sq
1db00 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
1db10 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 ] routines can b
1db20 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
1db30 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c .** an English l
1db40 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 anguage descript
1db50 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 ion of the error
1db60 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 following a fai
1db70 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f lure of any.** o
1db80 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 f the sqlite3_op
1db90 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a en() routines..*
1dba0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c *.** ^The defaul
1dbb0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 t encoding for t
1dbc0 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c he database will
1dbd0 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 be UTF-8 if.**
1dbe0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
1dbf0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
1dc00 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 2() is called an
1dc10 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 d.** UTF-16 in t
1dc20 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f he native byte o
1dc30 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f rder if sqlite3_
1dc40 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 open16() is used
1dc50 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 ..**.** Whether
1dc60 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 or not an error
1dc70 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 occurs when it i
1dc80 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 s opened, resour
1dc90 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ces.** associate
1dca0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 d with the [data
1dcb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1dcc0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 handle should b
1dcd0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a e released by.**
1dce0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
1dcf0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
1dd00 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c when it is no l
1dd10 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a onger required..
1dd20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1dd30 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 3_open_v2() inte
1dd40 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 rface works like
1dd50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a sqlite3_open().
1dd60 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 ** except that i
1dd70 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 t accepts two ad
1dd80 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 ditional paramet
1dd90 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ers for addition
1dda0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 al control.** ov
1ddb0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 er the new datab
1ddc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 ase connection.
1ddd0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 ^(The flags par
1dde0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c ameter to.** sql
1ddf0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 ite3_open_v2() c
1de00 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a an take one of.*
1de10 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * the following
1de20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 three values, op
1de30 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
1de40 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b d with the .** [
1de50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
1de60 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 TEX], [SQLITE_OP
1de70 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b EN_FULLMUTEX], [
1de80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
1de90 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 EDCACHE],.** [SQ
1dea0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
1deb0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 ECACHE], and/or
1dec0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 [SQLITE_OPEN_URI
1ded0 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a ] flags:)^.**.**
1dee0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b <dl>.** ^(<dt>[
1def0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
1df00 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ONLY]</dt>.** <d
1df10 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
1df20 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 s opened in read
1df30 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 -only mode. If
1df40 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 the database doe
1df50 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 s not.** already
1df60 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 exist, an error
1df70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
1df80 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 d>)^.**.** ^(<dt
1df90 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
1dfa0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a ADWRITE]</dt>.**
1dfb0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
1dfc0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
1dfd0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 reading and writ
1dfe0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c ing if possible,
1dff0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f or reading.** o
1e000 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 nly if the file
1e010 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 is write protect
1e020 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 ed by the operat
1e030 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 ing system. In
1e040 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 either.** case t
1e050 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 he database must
1e060 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 already exist,
1e070 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 otherwise an err
1e080 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c or is returned.<
1e090 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c /dd>)^.**.** ^(<
1e0a0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
1e0b0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
1e0c0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
1e0d0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
1e0e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
1e0f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 ened for reading
1e100 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e and writing, an
1e110 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a d is created if.
1e120 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 ** it does not a
1e130 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 lready exist. Th
1e140 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 is is the behavi
1e150 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 or that is alway
1e160 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 s used for.** sq
1e170 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
1e180 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
1e190 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 ).</dd>)^.** </d
1e1a0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 l>.**.** If the
1e1b0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
1e1c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1e1d0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 () is not one of
1e1e0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 the.** combinat
1e1f0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 ions shown above
1e200 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 optionally comb
1e210 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a ined with other.
1e220 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
1e230 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 READONLY | SQLIT
1e240 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a E_OPEN_* bits].*
1e250 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 * then the behav
1e260 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
1e270 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
1e280 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
1e290 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
1e2a0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 t, then the data
1e2b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1e2c0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 ** opens in the
1e2d0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 multi-thread [th
1e2e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 reading mode] as
1e2f0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e long as the sin
1e300 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f gle-thread.** mo
1e310 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 de has not been
1e320 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 set at compile-t
1e330 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
1e340 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b e. ^If the.** [
1e350 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
1e360 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
1e370 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 et then the data
1e380 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1e390 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 opens.** in the
1e3a0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 serialized [thre
1e3b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 ading mode] unle
1e3c0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 ss single-thread
1e3d0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 was.** previous
1e3e0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 ly selected at c
1e3f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
1e400 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 tart-time..** ^T
1e410 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
1e420 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 SHAREDCACHE] fla
1e430 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
1e440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1e450 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 to be.** eligib
1e460 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 le to use [share
1e470 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 d cache mode], r
1e480 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
1e490 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 ther or not shar
1e4a0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 ed.** cache is e
1e4b0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 nabled using [sq
1e4c0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
1e4d0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e red_cache()]. ^
1e4e0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f The.** [SQLITE_O
1e4f0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
1e500 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 ] flag causes th
1e510 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1e520 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 ction to not.**
1e530 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b participate in [
1e540 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 shared cache mod
1e550 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 e] even if it is
1e560 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 enabled..**.**
1e570 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 ^The fourth para
1e580 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1e590 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 _open_v2() is th
1e5a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a e name of the.**
1e5b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
1e5c0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e bject that defin
1e5d0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 es the operating
1e5e0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 system interfac
1e5f0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 e that.** the ne
1e600 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 w database conne
1e610 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 ction should use
1e620 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 . ^If the fourt
1e630 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
1e640 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 * a NULL pointer
1e650 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c then the defaul
1e660 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
1e670 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a object is used..
1e680 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 **.** ^If the fi
1e690 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f lename is ":memo
1e6a0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 ry:", then a pri
1e6b0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 vate, temporary
1e6c0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
1e6d0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 se.** is created
1e6e0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 for the connect
1e6f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d ion. ^This in-m
1e700 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 emory database w
1e710 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a ill vanish when.
1e720 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
1e730 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
1e740 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 osed. Future ve
1e750 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
1e760 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 might.** make u
1e770 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c se of additional
1e780 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d special filenam
1e790 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 es that begin wi
1e7a0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 th the ":" chara
1e7b0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 cter..** It is r
1e7c0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
1e7d0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 when a database
1e7e0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c filename actuall
1e7f0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 y does begin wit
1e800 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 h.** a ":" chara
1e810 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 cter you should
1e820 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e prefix the filen
1e830 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e ame with a pathn
1e840 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 ame such as.** "
1e850 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 ./" to avoid amb
1e860 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 iguity..**.** ^I
1e870 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
1e880 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e s an empty strin
1e890 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 g, then a privat
1e8a0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 e, temporary.**
1e8b0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 on-disk database
1e8c0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 will be created
1e8d0 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 . ^This private
1e8e0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
1e8f0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c e.** automatical
1e900 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f ly deleted as so
1e910 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 on as the databa
1e920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
1e930 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b closed..**.** [
1e940 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 [URI filenames i
1e950 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 n sqlite3_open()
1e960 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e ]] <h3>URI Filen
1e970 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 ames</h3>.**.**
1e980 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d ^If [URI filenam
1e990 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f e] interpretatio
1e9a0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e n is enabled, an
1e9b0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 d the filename a
1e9c0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e rgument.** begin
1e9d0 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 s with "file:",
1e9e0 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d then the filenam
1e9f0 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 e is interpreted
1ea00 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a as a URI. ^URI.
1ea10 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 ** filename inte
1ea20 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e rpretation is en
1ea30 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 abled if the [SQ
1ea40 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
1ea50 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e lag is.** set in
1ea60 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 the fourth argu
1ea70 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
1ea80 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 open_v2(), or if
1ea90 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 it has.** been
1eaa0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 enabled globally
1eab0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 using the [SQLI
1eac0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f TE_CONFIG_URI] o
1ead0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a ption with the.*
1eae0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
1eaf0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 g()] method or b
1eb00 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 y the [SQLITE_US
1eb10 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 E_URI] compile-t
1eb20 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 ime option..** A
1eb30 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 s of SQLite vers
1eb40 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 ion 3.7.7, URI f
1eb50 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 ilename interpre
1eb60 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 tation is turned
1eb70 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 off.** by defau
1eb80 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 lt, but future r
1eb90 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
1eba0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 e might enable U
1ebb0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 RI filename.** i
1ebc0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 nterpretation by
1ebd0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 default. See "
1ebe0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 [URI filenames]"
1ebf0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
1ec00 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a ** information..
1ec10 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 **.** URI filena
1ec20 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 mes are parsed a
1ec30 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 ccording to RFC
1ec40 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 3986. ^If the UR
1ec50 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a I contains an.**
1ec60 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e authority, then
1ec70 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 it must be eith
1ec80 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 er an empty stri
1ec90 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 ng or the string
1eca0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 .** "localhost"
1ecb0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 . ^If the author
1ecc0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d ity is not an em
1ecd0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c pty string or "l
1ece0 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a ocalhost", an .*
1ecf0 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 * error is retur
1ed00 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 ned to the calle
1ed10 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 r. ^The fragment
1ed20 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
1ed30 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 URI, if .** pres
1ed40 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e ent, is ignored.
1ed50 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 .**.** ^SQLite u
1ed60 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d ses the path com
1ed70 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 ponent of the UR
1ed80 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 I as the name of
1ed90 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a the disk file.*
1eda0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 * which contains
1edb0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e the database. ^
1edc0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 If the path begi
1edd0 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 ns with a '/' ch
1ede0 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 aracter, .** the
1edf0 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 n it is interpre
1ee00 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 ted as an absolu
1ee10 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 te path. ^If the
1ee20 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 path does not b
1ee30 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 egin .** with a
1ee40 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 '/' (meaning tha
1ee50 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 t the authority
1ee60 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 section is omitt
1ee70 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 ed from the URI)
1ee80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 .** then the pat
1ee90 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 h is interpreted
1eea0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 as a relative p
1eeb0 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e ath. .** ^On win
1eec0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 dows, the first
1eed0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 component of an
1eee0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a absolute path .*
1eef0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 * is a drive spe
1ef00 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e cification (e.g.
1ef10 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b "C:")..**.** [[
1ef20 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 core URI query p
1ef30 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 arameters]].** T
1ef40 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 he query compone
1ef50 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 nt of a URI may
1ef60 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 contain paramete
1ef70 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 rs that are inte
1ef80 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 rpreted.** eithe
1ef90 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 r by SQLite itse
1efa0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 lf, or by a [VFS
1efb0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d | custom VFS im
1efc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a plementation]..*
1efd0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 * SQLite interpr
1efe0 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ets the followin
1eff0 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61 g three query pa
1f000 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 rameters:.**.**
1f010 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c <ul>.** <li> <
1f020 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 b>vfs</b>: ^The
1f030 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 "vfs" parameter
1f040 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 may be used to s
1f050 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 pecify the name
1f060 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 of.** a VFS
1f070 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 object that prov
1f080 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 ides the operati
1f090 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 ng system interf
1f0a0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a ace that should.
1f0b0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 ** be used t
1f0c0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 o access the dat
1f0d0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 abase file on di
1f0e0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 sk. ^If this opt
1f0f0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a ion is set to.**
1f100 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 an empty st
1f110 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 ring the default
1f120 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 VFS object is u
1f130 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 sed. ^Specifying
1f140 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 an unknown.**
1f150 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 VFS is an err
1f160 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f or. ^If sqlite3_
1f170 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 open_v2() is use
1f180 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 d and the vfs op
1f190 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 tion is.** p
1f1a0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 resent, then the
1f1b0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 VFS specified b
1f1c0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b y the option tak
1f1d0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 es precedence ov
1f1e0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 er.** the va
1f1f0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
1f200 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
1f210 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
1f220 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 en_v2()..**.**
1f230 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 <li> <b>mode</b
1f240 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 >: ^(The mode pa
1f250 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 rameter may be s
1f260 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f et to either "ro
1f270 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20 ", "rw" or.**
1f280 20 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70 74 "rwc". Attempt
1f290 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f ing to set it to
1f2a0 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 any other value
1f2b0 20 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 is an error)^.
1f2c0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 .** ^If "ro"
1f2d0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 is specified, t
1f2e0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
1f2f0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
1f300 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 ead-only .**
1f310 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 access, just as
1f320 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
1f330 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 OPEN_READONLY] f
1f340 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 lag had been set
1f350 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 in the .**
1f360 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
1f370 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 o sqlite3_prepar
1f380 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 e_v2(). ^If the
1f390 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 mode option is s
1f3a0 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 et to .** "r
1f3b0 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 w", then the dat
1f3c0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
1f3d0 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 for read-write (
1f3e0 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 but not create)
1f3f0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 .** access,
1f400 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 as if SQLITE_OPE
1f410 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 N_READWRITE (but
1f420 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e not SQLITE_OPEN
1f430 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a _CREATE) had .**
1f440 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e been set. ^
1f450 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 Value "rwc" is e
1f460 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
1f470 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 ting both .**
1f480 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 SQLITE_OPEN_RE
1f490 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 ADWRITE and SQLI
1f4a0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 TE_OPEN_CREATE.
1f4b0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ^If sqlite3_open
1f4c0 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20 20 _v2() is .**
1f4d0 20 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e 20 used, it is an
1f4e0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 error to specify
1f4f0 20 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 a value for the
1f500 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 mode parameter
1f510 74 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20 20 that is .**
1f520 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 less restrictive
1f530 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 than that speci
1f540 66 69 65 64 20 62 79 20 74 68 65 20 66 6c 61 67 fied by the flag
1f550 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 s passed as the
1f560 74 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70 61 third .** pa
1f570 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 rameter..**.**
1f580 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f <li> <b>cache</
1f590 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 b>: ^The cache p
1f5a0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
1f5b0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 set to either "s
1f5c0 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 hared" or.**
1f5d0 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 "private". ^Set
1f5e0 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 ting it to "shar
1f5f0 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e ed" is equivalen
1f600 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 t to setting the
1f610 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f .** SQLITE_O
1f620 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 PEN_SHAREDCACHE
1f630 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 bit in the flags
1f640 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 argument passed
1f650 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 to.** sqlit
1f660 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 e3_open_v2(). ^S
1f670 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 etting the cache
1f680 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 parameter to "p
1f690 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 rivate" is .**
1f6a0 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f equivalent to
1f6b0 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c setting the SQL
1f6c0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
1f6d0 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 CACHE bit..**
1f6e0 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 ^If sqlite3_op
1f6f0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 en_v2() is used
1f700 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 and the "cache"
1f710 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 parameter is pre
1f720 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 sent in.** a
1f730 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 URI filename, i
1f740 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 ts value overrid
1f750 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 es any behaviour
1f760 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 requested by se
1f770 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c tting.** SQL
1f780 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
1f790 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f CACHE or SQLITE_
1f7a0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
1f7b0 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a flag..** </ul>.
1f7c0 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e **.** ^Specifyin
1f7d0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 g an unknown par
1f7e0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 ameter in the qu
1f7f0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 ery component of
1f800 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e a URI is not an
1f810 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 .** error. Futu
1f820 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
1f830 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 QLite might unde
1f840 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 rstand additiona
1f850 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d l query.** param
1f860 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 eters. See "[qu
1f870 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 ery parameters w
1f880 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e ith special mean
1f890 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 ing to SQLite]"
1f8a0 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 for.** additiona
1f8b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
1f8c0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e *.** [[URI filen
1f8d0 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c ame examples]] <
1f8e0 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 h3>URI filename
1f8f0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a examples</h3>.**
1f900 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
1f910 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 r="1" align=cent
1f920 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 er cellpadding=5
1f930 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 >.** <tr><th> UR
1f940 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e I filenames <th>
1f950 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e Results.** <tr>
1f960 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 <td> file:data.d
1f970 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 b <td> .**
1f980 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c Open the fil
1f990 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 e "data.db" in t
1f9a0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 he current direc
1f9b0 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 tory..** <tr><td
1f9c0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 > file:/home/fre
1f9d0 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a d/data.db<br>.**
1f9e0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f file:/
1f9f0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 //home/fred/data
1fa00 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 .db <br> .**
1fa10 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 file://loc
1fa20 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 alhost/home/fred
1fa30 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 /data.db <br> <t
1fa40 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
1fa50 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 Open the databas
1fa60 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 e file "/home/fr
1fa70 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 ed/data.db"..**
1fa80 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f <tr><td> file://
1fa90 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 darkstar/home/fr
1faa0 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 ed/data.db <td>
1fab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 .** An
1fac0 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 error. "darkstar
1fad0 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 " is not a recog
1fae0 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e nized authority.
1faf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c .** <tr><td styl
1fb00 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e e="white-space:n
1fb10 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 owrap"> .**
1fb20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f file:///C:/
1fb30 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 Documents%20and%
1fb40 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 20Settings/fred/
1fb50 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a Desktop/data.db.
1fb60 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 ** <td> Wind
1fb70 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 ows only: Open t
1fb80 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 he file "data.db
1fb90 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b " on fred's desk
1fba0 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 top on drive.**
1fbb0 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 C:. Not
1fbc0 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 e that the %20 e
1fbd0 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 scaping in this
1fbe0 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 example is not s
1fbf0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 trictly .**
1fc00 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d necessary -
1fc10 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 space character
1fc20 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 s can be used li
1fc30 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 terally.**
1fc40 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e in URI filen
1fc50 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 ames..** <tr><td
1fc60 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d > file:data.db?m
1fc70 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 ode=ro&cache=pri
1fc80 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 vate <td> .**
1fc90 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 Open file
1fca0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 "data.db" in th
1fcb0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 e current direct
1fcc0 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c ory for read-onl
1fcd0 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 y access..**
1fce0 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 Regardless
1fcf0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
1fd00 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 ot shared-cache
1fd10 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 mode is enabled
1fd20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 by.** d
1fd30 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 efault, use a pr
1fd40 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 ivate cache..**
1fd50 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 <tr><td> file:/h
1fd60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
1fd70 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b ?vfs=unix-nolock
1fd80 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <td>.**
1fd90 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f Open file "/ho
1fda0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 me/fred/data.db"
1fdb0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 . Use the specia
1fdc0 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f l VFS "unix-nolo
1fdd0 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ck"..** <tr><td>
1fde0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f file:data.db?mo
1fdf0 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e de=readonly <td>
1fe00 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e .** An
1fe10 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c error. "readonl
1fe20 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 y" is not a vali
1fe30 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 d option for the
1fe40 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 "mode" paramete
1fe50 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a r..** </table>.*
1fe60 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 *.** ^URI hexade
1fe70 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 cimal escape seq
1fe80 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 uences (%HH) are
1fe90 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 supported withi
1fea0 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a n the path and.*
1feb0 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e * query componen
1fec0 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 ts of a URI. A h
1fed0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 exadecimal escap
1fee0 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 e sequence consi
1fef0 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 sts of a.** perc
1ff00 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d ent sign - "%" -
1ff10 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 followed by exa
1ff20 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 ctly two hexadec
1ff30 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 imal digits .**
1ff40 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 specifying an oc
1ff50 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f tet value. ^Befo
1ff60 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 re the path or q
1ff70 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 uery components
1ff80 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 of a.** URI file
1ff90 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 name are interpr
1ffa0 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 eted, they are e
1ffb0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 ncoded using UTF
1ffc0 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 -8 and all .** h
1ffd0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 exadecimal escap
1ffe0 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c e sequences repl
1fff0 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 aced by a single
20000 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 byte containing
20010 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f the.** correspo
20020 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 nding octet. If
20030 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e this process gen
20040 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 erates an invali
20050 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 d UTF-8 encoding
20060 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 ,.** the results
20070 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
20080 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f **.** <b>Note to
20090 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c Windows users:<
200a0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e /b> The encodin
200b0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 g used for the f
200c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
200d0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f .** of sqlite3_o
200e0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
200f0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 3_open_v2() must
20100 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 be UTF-8, not w
20110 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 hatever.** codep
20120 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 age is currently
20130 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e defined. Filen
20140 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ames containing
20150 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a international.**
20160 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 characters must
20170 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f be converted to
20180 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 UTF-8 prior to
20190 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 passing them int
201a0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
201b0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
201c0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 pen_v2()..*/.int
201d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 sqlite3_open(.
201e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
201f0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
20200 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
20210 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
20220 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
20230 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
20240 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
20250 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 ;.int sqlite3_op
20260 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f en16(. const vo
20270 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 id *filename,
20280 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
20290 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f name (UTF-16) */
202a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
202b0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b /* OU
202c0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
202d0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 dle */.);.int sq
202e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 lite3_open_v2(.
202f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
20300 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
20310 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
20320 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
20330 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 e3 **ppDb,
20340 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
20350 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 e db handle */.
20360 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 int flags,
20370 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 /* Flag
20380 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 s */. const cha
20390 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f r *zVfs /
203a0 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f * Name of VFS mo
203b0 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 dule to use */.)
203c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
203d0 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 F: Obtain Values
203e0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 For URI Paramet
203f0 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ers.**.** These
20400 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 are utility rout
20410 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 ines, useful to
20420 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
20430 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a ons, that check.
20440 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 ** to see if a d
20450 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 atabase file was
20460 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 a URI that cont
20470 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 ained a specific
20480 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d query .** param
20490 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 eter, and if so
204a0 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 obtains the valu
204b0 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 e of that query
204c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
204d0 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 If F is the dat
204e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 abase filename p
204f0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e ointer passed in
20500 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d to the xOpen() m
20510 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 ethod of .** a V
20520 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
20530 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 n when the flags
20540 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
20550 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 pen() has one or
20560 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 .** more of the
20570 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
20580 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 I] or [SQLITE_OP
20590 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 EN_MAIN_DB] bits
205a0 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 set and.** P is
205b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
205c0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
205d0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 , then.** sqlite
205e0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
205f0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 F,P) returns the
20600 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a value of the P.
20610 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 ** parameter if
20620 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e it exists or a N
20630 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 ULL pointer if P
20640 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 does not appear
20650 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 as a .** query
20660 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 parameter on F.
20670 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 If P is a query
20680 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a parameter of F.
20690 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 ** has no explic
206a0 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 it value, then s
206b0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
206c0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e eter(F,P) return
206d0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 s.** a pointer t
206e0 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e o an empty strin
206f0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c g..**.** The sql
20700 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
20710 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 (F,P,B) routine
20720 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 assumes that P i
20730 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 s a boolean.** p
20740 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
20750 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 urns true (1) or
20760 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 false (0) accor
20770 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 ding to the valu
20780 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 e.** of P. The
20790 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
207a0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 ean(F,P,B) routi
207b0 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 ne returns true
207c0 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 (1) if the.** va
207d0 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 lue of query par
207e0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 ameter P is one
207f0 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 of "yes", "true"
20800 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 , or "on" in any
20810 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 .** case or if t
20820 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 he value begins
20830 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 with a non-zero
20840 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a number. The .**
20850 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
20860 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
20870 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c ines returns fal
20880 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 se (0) if the va
20890 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 lue of.** query
208a0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f parameter P is o
208b0 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c ne of "no", "fal
208c0 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e se", or "off" in
208d0 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 any case or.**
208e0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 if the value beg
208f0 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 ins with a numer
20900 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 ic zero. If P i
20910 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a s not a query.**
20920 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 parameter on F
20930 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 or if the value
20940 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 of P is does not
20950 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 match any of th
20960 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e e.** above, then
20970 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
20980 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 lean(F,P,B) retu
20990 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a rns (B!=0)..**.*
209a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 * The sqlite3_ur
209b0 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 i_int64(F,P,D) r
209c0 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 outine converts
209d0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 the value of P i
209e0 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 nto a.** 64-bit
209f0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 signed integer a
20a00 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 nd returns that
20a10 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 integer, or D if
20a20 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 P does not.** e
20a30 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 xist. If the va
20a40 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 lue of P is some
20a50 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
20a60 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 an integer, the
20a70 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 n.** zero is ret
20a80 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 urned..** .** If
20a90 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 F is a NULL poi
20aa0 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 nter, then sqlit
20ab0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
20ac0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 (F,P) returns NU
20ad0 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 LL and.** sqlite
20ae0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 3_uri_boolean(F,
20af0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 P,B) returns B.
20b00 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e If F is not a N
20b10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a ULL pointer and.
20b20 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 ** is not a data
20b30 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 base file pathna
20b40 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 me pointer that
20b50 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e SQLite passed in
20b60 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 to the xOpen.**
20b70 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e VFS method, then
20b80 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
20b90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
20ba0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
20bb0 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 robably.** undes
20bc0 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 irable..*/.const
20bd0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 char *sqlite3_u
20be0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e ri_parameter(con
20bf0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 st char *zFilena
20c00 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a me, const char *
20c10 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c zParam);.int sql
20c20 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
20c30 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 (const char *zFi
20c40 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a le, const char *
20c50 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 zParam, int bDef
20c60 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 ault);.sqlite3_i
20c70 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 nt64 sqlite3_uri
20c80 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 _int64(const cha
20c90 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c r*, const char*,
20ca0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
20cb0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
20cc0 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 F: Error Codes A
20cd0 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a nd Messages.**.*
20ce0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
20cf0 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 rrcode() interfa
20d00 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
20d10 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 umeric [result c
20d20 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 ode] or.** [exte
20d30 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
20d40 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 ] for the most r
20d50 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c ecent failed sql
20d60 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a ite3_* API call.
20d70 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
20d80 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
20d90 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 onnection]. If a
20da0 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 prior API call
20db0 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 failed.** but th
20dc0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 e most recent AP
20dd0 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 I call succeeded
20de0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
20df0 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 ue from.** sqlit
20e00 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 e3_errcode() is
20e10 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 undefined. ^The
20e20 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
20e30 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 d_errcode().** i
20e40 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 nterface is the
20e50 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 same except that
20e60 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 it always retur
20e70 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 ns the .** [exte
20e80 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
20e90 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 ] even when exte
20ea0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
20eb0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 s are.** disable
20ec0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
20ed0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 lite3_errmsg() a
20ee0 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 nd sqlite3_errms
20ef0 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 g16() return Eng
20f00 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a lish-language.**
20f10 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 text that descr
20f20 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 ibes the error,
20f30 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
20f40 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 or UTF-16 respec
20f50 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d tively..** ^(Mem
20f60 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
20f70 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
20f80 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 ring is managed
20f90 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 internally..** T
20fa0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
20fb0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
20fc0 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 worry about free
20fd0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a ing the result..
20fe0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 ** However, the
20ff0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 error string mig
21000 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 ht be overwritte
21010 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 n or deallocated
21020 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e by.** subsequen
21030 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 t calls to other
21040 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
21050 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a e functions.)^.*
21060 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 *.** When the se
21070 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 rialized [thread
21080 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 ing mode] is in
21090 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 use, it might be
210a0 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 the.** case tha
210b0 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 t a second error
210c0 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 occurs on a sep
210d0 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 arate thread in
210e0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 between.** the t
210f0 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 ime of the first
21100 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 error and the c
21110 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 all to these int
21120 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e erfaces..** When
21130 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 that happens, t
21140 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 he second error
21150 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 will be reported
21160 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 since these.**
21170 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 interfaces alway
21180 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 s report the mos
21190 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e t recent result.
211a0 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 To avoid.** th
211b0 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 is, each thread
211c0 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 can obtain exclu
211d0 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 sive use of the
211e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
211f0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e tion] D.** by in
21200 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f voking [sqlite3_
21210 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 mutex_enter]([sq
21220 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 lite3_db_mutex](
21230 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e D)) before begin
21240 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 ning.** to use D
21250 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 and invoking [s
21260 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 qlite3_mutex_lea
21270 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f ve]([sqlite3_db_
21280 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 mutex](D)) after
21290 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f .** all calls to
212a0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 the interfaces
212b0 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 listed here are
212c0 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a completed..**.**
212d0 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 If an interface
212e0 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 fails with SQLI
212f0 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 TE_MISUSE, that
21300 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 means the interf
21310 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b ace.** was invok
21320 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 ed incorrectly b
21330 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
21340 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 n. In that case
21350 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 , the.** error c
21360 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 ode and message
21370 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 may or may not b
21380 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 e set..*/.int sq
21390 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 lite3_errcode(sq
213a0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 lite3 *db);.int
213b0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
213c0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 _errcode(sqlite3
213d0 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 *db);.const cha
213e0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r *sqlite3_errms
213f0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e g(sqlite3*);.con
21400 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
21410 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 _errmsg16(sqlite
21420 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
21430 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 3REF: SQL Statem
21440 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 ent Object.** KE
21450 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 YWORDS: {prepare
21460 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 d statement} {pr
21470 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
21480 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 s}.**.** An inst
21490 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
214a0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 ect represents a
214b0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 single SQL stat
214c0 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f ement..** This o
214d0 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 bject is various
214e0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 ly known as a "p
214f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
21500 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 t" or a.** "comp
21510 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 iled SQL stateme
21520 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 nt" or simply as
21530 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a a "statement"..
21540 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f **.** The life o
21550 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 f a statement ob
21560 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 ject goes someth
21570 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a ing like this:.*
21580 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
21590 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a > Create the obj
215a0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ect using [sqlit
215b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
215c0 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a or a related.**
215d0 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a function..
215e0 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c ** <li> Bind val
215f0 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 ues to [host par
21600 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 ameters] using t
21610 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
21620 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 *().** inte
21630 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 rfaces..** <li>
21640 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 Run the SQL by c
21650 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
21660 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d step()] one or m
21670 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c ore times..** <l
21680 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 i> Reset the sta
21690 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 tement using [sq
216a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 lite3_reset()] t
216b0 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 hen go back.**
216c0 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 to step 2.
216d0 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 Do this zero or
216e0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c more times..** <
216f0 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 li> Destroy the
21700 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 object using [sq
21710 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
21720 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a ]..** </ol>.**.*
21730 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d * Refer to docum
21740 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 entation on indi
21750 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 vidual methods a
21760 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f bove for additio
21770 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 nal.** informati
21780 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 on..*/.typedef s
21790 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 truct sqlite3_st
217a0 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b mt sqlite3_stmt;
217b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
217c0 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 : Run-time Limit
217d0 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 s.**.** ^(This i
217e0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 nterface allows
217f0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 the size of vari
21800 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 ous constructs t
21810 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 o be limited.**
21820 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 on a connection
21830 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 by connection ba
21840 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 sis. The first
21850 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
21860 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
21870 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 nnection] whose
21880 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 limit is to be s
21890 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 et or queried.
218a0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 The.** second pa
218b0 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f rameter is one o
218c0 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 f the [limit cat
218d0 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 egories] that de
218e0 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 fine a.** class
218f0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f of constructs to
21900 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 be size limited
21910 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 . The third par
21920 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
21930 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 new limit for t
21940 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e hat construct.)^
21950 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e .**.** ^If the n
21960 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 ew limit is a ne
21970 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 gative number, t
21980 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 he limit is unch
21990 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 anged..** ^(For
219a0 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 each limit categ
219b0 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ory SQLITE_LIMIT
219c0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 _<i>NAME</i> the
219d0 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d re is a .** [lim
219e0 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 its | hard upper
219f0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 bound].** set a
21a00 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 t compile-time b
21a10 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 y a C preprocess
21a20 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a or macro called.
21a30 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c ** [limits | SQL
21a40 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c ITE_MAX_<i>NAME<
21a50 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f /i>]..** (The "_
21a60 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e LIMIT_" in the n
21a70 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 ame is changed t
21a80 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a o "_MAX_".))^.**
21a90 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e ^Attempts to in
21aa0 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 crease a limit a
21ab0 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 bove its hard up
21ac0 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a per bound are.**
21ad0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 silently trunca
21ae0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 ted to the hard
21af0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a upper bound..**.
21b00 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f ** ^Regardless o
21b10 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
21b20 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 the limit was c
21b30 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 hanged, the .**
21b40 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
21b50 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
21b60 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 rns the prior va
21b70 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 lue of the limit
21b80 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 ..** ^Hence, to
21b90 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 find the current
21ba0 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 value of a limi
21bb0 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 t without changi
21bc0 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 ng it,.** simply
21bd0 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 invoke this int
21be0 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 erface with the
21bf0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
21c00 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a set to -1..**.**
21c10 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 Run-time limits
21c20 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
21c30 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 r use in applica
21c40 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 tions that manag
21c50 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 e.** both their
21c60 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 own internal dat
21c70 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 abase and also d
21c80 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 atabases that ar
21c90 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 e controlled.**
21ca0 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 by untrusted ext
21cb0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 ernal sources.
21cc0 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 An example appli
21cd0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 cation might be
21ce0 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 a.** web browser
21cf0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 that has its ow
21d00 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 n databases for
21d10 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 storing history
21d20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 and.** separate
21d30 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f databases contro
21d40 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 lled by JavaScri
21d50 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 pt applications
21d60 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 downloaded.** of
21d70 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 f the Internet.
21d80 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 The internal da
21d90 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 tabases can be g
21da0 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 iven the.** larg
21db0 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 e, default limit
21dc0 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 s. Databases ma
21dd0 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 naged by externa
21de0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a l sources can.**
21df0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 be given much s
21e00 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 maller limits de
21e10 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e signed to preven
21e20 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 t a denial of se
21e30 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e rvice.** attack.
21e40 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 Developers mig
21e50 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 ht also want to
21e60 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 use the [sqlite3
21e70 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
21e80 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 )].** interface
21e90 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 to further contr
21ea0 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c ol untrusted SQL
21eb0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 . The size of t
21ec0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
21ed0 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 reated by an unt
21ee0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 rusted script ca
21ef0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 n be contained u
21f00 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 sing the.** [max
21f10 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
21f20 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 AGMA]..**.** New
21f30 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 run-time limit
21f40 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 categories may b
21f50 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
21f60 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 e releases..*/.i
21f70 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 nt sqlite3_limit
21f80 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 (sqlite3*, int i
21f90 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a d, int newVal);.
21fa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
21fb0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 Run-Time Limit
21fc0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 Categories.** KE
21fd0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 YWORDS: {limit c
21fe0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 ategory} {*limit
21ff0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a categories}.**.
22000 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
22010 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 ts define variou
22020 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 s performance li
22030 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e mits.** that can
22040 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 be lowered at r
22050 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 un-time using [s
22060 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e qlite3_limit()].
22070 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 .** The synopsis
22080 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 of the meanings
22090 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 of the various
220a0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 limits is shown
220b0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 below..** Additi
220c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
220d0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 is available at
220e0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 [limits | Limit
220f0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a s in SQLite]..**
22100 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 .** <dl>.** [[SQ
22110 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
22120 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
22130 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 _LIMIT_LENGTH</d
22140 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
22150 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e ximum size of an
22160 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 y string or BLOB
22170 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 or table row, i
22180 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a n bytes.<dd>)^.*
22190 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
221a0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d MIT_SQL_LENGTH]]
221b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
221c0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f MIT_SQL_LENGTH</
221d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
221e0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
221f0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
22200 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 t, in bytes.</dd
22210 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
22220 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d TE_LIMIT_COLUMN]
22230 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
22240 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e IMIT_COLUMN</dt>
22250 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
22260 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f mum number of co
22270 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 lumns in a table
22280 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 definition or i
22290 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 n the.** result
222a0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
222b0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d ] or the maximum
222c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
222d0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a ns in an index.*
222e0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 * or in an ORDER
222f0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 BY or GROUP BY
22300 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a clause.</dd>)^.*
22310 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
22320 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d MIT_EXPR_DEPTH]]
22330 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
22340 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f MIT_EXPR_DEPTH</
22350 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
22360 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 aximum depth of
22370 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f the parse tree o
22380 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e n any expression
22390 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
223a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f [SQLITE_LIMIT_CO
223b0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 MPOUND_SELECT]]
223c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
223d0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
223e0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 CT</dt>.** <dd>T
223f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
22400 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 r of terms in a
22410 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 compound SELECT
22420 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 statement.</dd>)
22430 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
22440 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d _LIMIT_VDBE_OP]]
22450 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
22460 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e MIT_VDBE_OP</dt>
22470 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
22480 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e mum number of in
22490 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 structions in a
224a0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
224b0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 program.** used
224c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 to implement an
224d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
224e0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f This limit is no
224f0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 t currently.** e
22500 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 nforced, though
22510 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 that might be ad
22520 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ded in some futu
22530 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a re release of.**
22540 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a SQLite.</dd>)^.
22550 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
22560 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
22570 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 G]] ^(<dt>SQLITE
22580 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
22590 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
225a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
225b0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
225c0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
225d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
225e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
225f0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 HED]] ^(<dt>SQLI
22600 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
22610 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
22620 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
22630 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 of [ATTACH | at
22640 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
22650 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
22660 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
22670 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
22680 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 TH]].** ^(<dt>SQ
22690 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
226a0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f PATTERN_LENGTH</
226b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
226c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
226d0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 the pattern arg
226e0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 ument to the [LI
226f0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d KE] or.** [GLOB]
22700 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e operators.</dd>
22710 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
22720 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
22730 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c _NUMBER]].** ^(<
22740 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
22750 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c VARIABLE_NUMBER<
22760 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
22770 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 maximum index nu
22780 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 mber of any [par
22790 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 ameter] in an SQ
227a0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a L statement.)^.*
227b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
227c0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
227d0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
227e0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
227f0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
22800 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
22810 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 th of recursion
22820 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 for triggers.</d
22830 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f d>)^.** </dl>.*/
22840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22850 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 LIMIT_LENGTH
22860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
22870 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
22880 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
22890 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
228a0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
228b0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 E_LIMIT_COLUMN
228c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
228d0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
228e0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 TE_LIMIT_EXPR_DE
228f0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 PTH
22900 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
22910 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
22920 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 ND_SELECT
22930 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
22940 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
22950 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 OP
22960 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 5.#define S
22970 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
22980 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 TION_ARG
22990 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 6.#define
229a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
229b0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 ACHED
229c0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
229d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 SQLITE_LIMIT_LI
229e0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 KE_PATTERN_LENGT
229f0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e H 8.#defin
22a00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
22a10 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 ARIABLE_NUMBER
22a20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 9.#defi
22a30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
22a40 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 TRIGGER_DEPTH
22a50 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 10../*.
22a60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
22a70 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 piling An SQL St
22a80 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f atement.** KEYWO
22a90 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d RDS: {SQL statem
22aa0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a ent compiler}.**
22ab0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 .** To execute a
22ac0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 n SQL query, it
22ad0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f must first be co
22ae0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 mpiled into a by
22af0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 te-code.** progr
22b00 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 am using one of
22b10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
22b20 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
22b30 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 argument, "db",
22b40 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 is a [database c
22b50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 onnection] obtai
22b60 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 ned from a.** pr
22b70 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
22b80 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
22b90 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
22ba0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 3_open_v2()] or.
22bb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
22bc0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 16()]. The data
22bd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
22be0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 must not have be
22bf0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a en closed..**.**
22c00 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
22c10 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 ment, "zSql", is
22c20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
22c30 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 o be compiled, e
22c40 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 ncoded.** as eit
22c50 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
22c60 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 -16. The sqlite
22c70 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 3_prepare() and
22c80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
22c90 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 v2().** interfac
22ca0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e es use UTF-8, an
22cb0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
22cc0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 e16() and sqlite
22cd0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
22ce0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a .** use UTF-16..
22cf0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 **.** ^If the nB
22d00 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 yte argument is
22d10 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 less than zero,
22d20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 then zSql is rea
22d30 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 d up to the.** f
22d40 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
22d50 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 ator. ^If nByte
22d60 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
22d70 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 then it is the
22d80 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 maximum.** numbe
22d90 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 r of bytes read
22da0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 from zSql. ^Wh
22db0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d en nByte is non-
22dc0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a negative, the.**
22dd0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 zSql string end
22de0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 s at either the
22df0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 first '\000' or
22e00 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 '\u0000' charact
22e10 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 er or.** the nBy
22e20 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 te-th byte, whic
22e30 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 hever comes firs
22e40 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 t. If the caller
22e50 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 knows.** that t
22e60 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 he supplied stri
22e70 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e ng is nul-termin
22e80 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 ated, then there
22e90 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 is a small.** p
22ea0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e erformance advan
22eb0 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 tage to be gaine
22ec0 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 d by passing an
22ed0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 nByte parameter
22ee0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c that.** is equal
22ef0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f to the number o
22f00 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 f bytes in the i
22f10 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 nput string <i>i
22f20 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 ncluding</i>.**
22f30 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 the nul-terminat
22f40 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73 or bytes as this
22f50 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 saves SQLite fr
22f60 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 om having to.**
22f70 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 make a copy of t
22f80 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e he input string.
22f90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 .**.** ^If pzTai
22fa0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 l is not NULL th
22fb0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 en *pzTail is ma
22fc0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 de to point to t
22fd0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a he first byte.**
22fe0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 past the end of
22ff0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 the first SQL s
23000 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c tatement in zSql
23010 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 . These routine
23020 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c s only.** compil
23030 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 e the first stat
23040 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 ement in zSql, s
23050 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 o *pzTail is lef
23060 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a t pointing to.**
23070 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e what remains un
23080 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 compiled..**.**
23090 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 ^*ppStmt is left
230a0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 pointing to a c
230b0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 ompiled [prepare
230c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
230d0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 t can be.** exec
230e0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 uted using [sqli
230f0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 te3_step()]. ^I
23100 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 f there is an er
23110 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 ror, *ppStmt is
23120 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 set.** to NULL.
23130 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 ^If the input t
23140 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 ext contains no
23150 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 SQL (if the inpu
23160 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a t is an empty.**
23170 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d string or a com
23180 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 ment) then *ppSt
23190 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c mt is set to NUL
231a0 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e L..** The callin
231b0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 g procedure is r
231c0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 esponsible for d
231d0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 eleting the comp
231e0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 iled.** SQL stat
231f0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c ement using [sql
23200 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
23210 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 after it has fi
23220 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a nished with it..
23230 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f ** ppStmt may no
23240 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a t be NULL..**.**
23250 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 ^On success, th
23260 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
23270 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f e() family of ro
23280 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
23290 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 QLITE_OK];.** ot
232a0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
232b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
232c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ned..**.** The s
232d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
232e0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 2() and sqlite3_
232f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 prepare16_v2() i
23300 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a nterfaces are.**
23310 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
23320 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d all new program
23330 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 s. The two older
23340 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
23350 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 retained.** for
23360 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
23370 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 ibility, but the
23380 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 ir use is discou
23390 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 raged..** ^In th
233a0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
233b0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 s, the prepared
233c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 statement.** tha
233d0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 t is returned (t
233e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
233f0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 ] object) contai
23400 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ns a copy of the
23410 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c .** original SQL
23420 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 text. This caus
23430 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f es the [sqlite3_
23440 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 step()] interfac
23450 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 e to.** behave d
23460 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 ifferently in th
23470 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 ree ways:.**.**
23480 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 <ol>.** <li>.**
23490 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 ^If the database
234a0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c schema changes,
234b0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 instead of retu
234c0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 rning [SQLITE_SC
234d0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 HEMA] as it.** a
234e0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f lways used to do
234f0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
23500 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 )] will automati
23510 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 cally recompile
23520 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 the SQL.** state
23530 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 ment and try to
23540 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a run it again..**
23550 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 </li>.**.** <li
23560 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 >.** ^When an er
23570 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c ror occurs, [sql
23580 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
23590 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 l return one of
235a0 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 the detailed.**
235b0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 [error codes] or
235c0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 [extended error
235d0 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c codes]. ^The l
235e0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 egacy behavior w
235f0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 as that.** [sqli
23600 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c te3_step()] woul
23610 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 d only return a
23620 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f generic [SQLITE_
23630 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f ERROR] result co
23640 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 de.** and the ap
23650 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 plication would
23660 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 have to make a s
23670 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 econd call to [s
23680 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a qlite3_reset()].
23690 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 ** in order to f
236a0 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 ind the underlyi
236b0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 ng cause of the
236c0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 problem. With th
236d0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a e "v2" prepare.*
236e0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 * interfaces, th
236f0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 e underlying rea
23700 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f son for the erro
23710 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d r is returned im
23720 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f mediately..** </
23730 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a li>.**.** <li>.*
23740 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 * ^If the specif
23750 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 ic value bound t
23760 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 o [parameter | h
23770 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 ost parameter] i
23780 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 n the .** WHERE
23790 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 clause might inf
237a0 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 luence the choic
237b0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 e of query plan
237c0 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c for a statement,
237d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 .** then the sta
237e0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 tement will be a
237f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 utomatically rec
23800 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 ompiled, as if t
23810 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a here had been .*
23820 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 * a schema chang
23830 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 e, on the first
23840 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
23850 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 ] call following
23860 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 any change.** t
23870 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 o the [sqlite3_b
23880 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 ind_text | bindi
23890 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 ngs] of that [pa
238a0 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 rameter]. .** ^T
238b0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 he specific valu
238c0 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 e of WHERE-claus
238d0 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 e [parameter] mi
238e0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 ght influence th
238f0 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 e .** choice of
23900 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 query plan if th
23910 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 e parameter is t
23920 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 he left-hand sid
23930 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a e of a [LIKE].**
23940 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 or [GLOB] opera
23950 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 tor or if the pa
23960 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 rameter is compa
23970 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 red to an indexe
23980 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 d column.** and
23990 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 the [SQLITE_ENAB
239a0 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c LE_STAT3] compil
239b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 e-time option is
239c0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 enabled..** the
239d0 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f .** </li>.** </
239e0 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ol>.*/.int sqlit
239f0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 e3_prepare(. sq
23a00 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
23a10 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
23a20 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
23a30 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 nst char *zSql,
23a40 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
23a50 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e tement, UTF-8 en
23a60 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
23a70 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
23a80 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
23a90 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
23aa0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
23ab0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
23ac0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
23ad0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
23ae0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 const char **p
23af0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
23b00 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
23b10 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
23b20 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 Sql */.);.int sq
23b30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
23b40 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
23b50 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
23b60 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
23b70 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
23b80 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
23b90 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
23ba0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 F-8 encoded */.
23bb0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
23bc0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
23bd0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
23be0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
23bf0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
23c00 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
23c10 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
23c20 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
23c30 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 ar **pzTail
23c40 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
23c50 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
23c60 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
23c70 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
23c80 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 are16(. sqlite3
23c90 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
23ca0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
23cb0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
23cc0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
23cd0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
23ce0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
23cf0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
23d00 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
23d10 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
23d20 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
23d30 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
23d40 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
23d50 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
23d60 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
23d70 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
23d80 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
23d90 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
23da0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
23db0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
23dc0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 3_prepare16_v2(.
23dd0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
23de0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
23df0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
23e00 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
23e10 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
23e20 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
23e30 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
23e40 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
23e50 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
23e60 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
23e70 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
23e80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
23e90 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
23ea0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
23eb0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
23ec0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
23ed0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
23ee0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
23ef0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a of zSql */.);..
23f00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
23f10 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 Retrieving State
23f20 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e ment SQL.**.** ^
23f30 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
23f40 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 an be used to re
23f50 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 trieve a saved c
23f60 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 opy of the origi
23f70 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 nal.** SQL text
23f80 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 used to create a
23f90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
23fa0 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 ment] if that st
23fb0 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 atement was.** c
23fc0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 ompiled using ei
23fd0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
23fe0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b epare_v2()] or [
23ff0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
24000 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 6_v2()]..*/.cons
24010 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
24020 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 sql(sqlite3_stmt
24030 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
24040 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 CAPI3REF: Deter
24050 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 mine If An SQL S
24060 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 tatement Writes
24070 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a The Database.**.
24080 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
24090 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 stmt_readonly(X)
240a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
240b0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
240c0 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c o) if.** and onl
240d0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 y if the [prepar
240e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 ed statement] X
240f0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 makes no direct
24100 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 changes to.** th
24110 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
24120 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a database file..
24130 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
24140 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
24150 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
24160 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 ns] or.** [virtu
24170 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 al tables] might
24180 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 change the data
24190 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 base indirectly
241a0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 as a side effect
241b0 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 . .** ^(For exa
241c0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c mple, if an appl
241d0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 ication defines
241e0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c a function "eval
241f0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c ()" that .** cal
24200 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ls [sqlite3_exec
24210 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f ()], then the fo
24220 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 llowing SQL stat
24230 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 ement would.** c
24240 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
24250 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 se file through
24260 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a side-effects:.**
24270 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
24280 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 <pre>.** SELE
24290 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 CT eval('DELETE
242a0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 FROM t1') FROM t
242b0 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 2;.** </pre></bl
242c0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
242d0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 But because the
242e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
242f0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nt does not chan
24300 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
24310 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 file.** directly
24320 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 , sqlite3_stmt_r
24330 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 eadonly() would
24340 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 still return tru
24350 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e e.)^.**.** ^Tran
24360 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 saction control
24370 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 statements such
24380 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d as [BEGIN], [COM
24390 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d MIT], [ROLLBACK]
243a0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d ,.** [SAVEPOINT]
243b0 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 , and [RELEASE]
243c0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 cause sqlite3_st
243d0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
243e0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a return true,.**
243f0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 since the state
24400 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 ments themselves
24410 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 do not actually
24420 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
24430 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 base but.** rath
24440 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 er they control
24450 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 the timing of wh
24460 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 en other stateme
24470 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a nts modify the .
24480 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 ** database. ^T
24490 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 he [ATTACH] and
244a0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 [DETACH] stateme
244b0 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a nts also cause.*
244c0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 * sqlite3_stmt_r
244d0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 eadonly() to ret
244e0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 urn true since,
244f0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 while those stat
24500 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 ements.** change
24510 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
24520 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 on of a database
24530 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 connection, the
24540 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a y do not make .*
24550 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 * changes to the
24560 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
24570 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f database files o
24580 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 n disk..*/.int s
24590 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
245a0 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d only(sqlite3_stm
245b0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
245c0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 * CAPI3REF: Dete
245d0 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 rmine If A Prepa
245e0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 red Statement Ha
245f0 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a s Been Reset.**.
24600 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
24610 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 stmt_busy(S) int
24620 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
24630 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 rue (non-zero) i
24640 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 f the.** [prepar
24650 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
24660 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 has been stepped
24670 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 at least once u
24680 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 sing .** [sqlite
24690 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 3_step(S)] but h
246a0 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f as not run to co
246b0 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 mpletion and/or
246c0 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e has not .** been
246d0 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 reset using [sq
246e0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e lite3_reset(S)].
246f0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ^The sqlite3_s
24700 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 tmt_busy(S).** i
24710 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
24720 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 false if S is a
24730 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
24740 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a If S is not a .*
24750 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 * NULL pointer a
24760 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e nd is not a poin
24770 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b ter to a valid [
24780 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
24790 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 nt].** object, t
247a0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
247b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e is undefined an
247c0 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 d probably undes
247d0 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 irable..**.** Th
247e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
247f0 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 be used in comb
24800 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 ination [sqlite3
24810 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a _next_stmt()].**
24820 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 to locate all p
24830 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
24840 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ts associated wi
24850 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a th a database .*
24860 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 * connection tha
24870 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 t are in need of
24880 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 being reset. T
24890 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c his can be used,
248a0 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c .** for example,
248b0 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 in diagnostic r
248c0 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 outines to searc
248d0 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a h for prepared .
248e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 ** statements th
248f0 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 at are holding a
24900 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 transaction ope
24910 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 n..*/.int sqlite
24920 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 3_stmt_busy(sqli
24930 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
24940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e ** CAPI3REF: Dyn
24950 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 amically Typed V
24960 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b alue Object.** K
24970 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 EYWORDS: {protec
24980 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
24990 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 e} {unprotected
249a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a sqlite3_value}.*
249b0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
249c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c the sqlite3_val
249d0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 ue object to rep
249e0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 resent all value
249f0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 s.** that can be
24a00 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 stored in a dat
24a10 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c abase table. SQL
24a20 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
24a30 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 typing.** for t
24a40 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f he values it sto
24a50 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 res. ^Values st
24a60 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f ored in sqlite3_
24a70 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a value objects.**
24a80 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 can be integers
24a90 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 , floating point
24aa0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 values, strings
24ab0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c , BLOBs, or NULL
24ac0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 ..**.** An sqlit
24ad0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
24ae0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 may be either "p
24af0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e rotected" or "un
24b00 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 protected"..** S
24b10 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 ome interfaces r
24b20 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 equire a protect
24b30 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
24b40 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 . Other interfa
24b50 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 ces.** will acce
24b60 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 pt either a prot
24b70 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 ected or an unpr
24b80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
24b90 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 value..** Every
24ba0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
24bb0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 ccepts sqlite3_v
24bc0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 alue arguments s
24bd0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 pecifies.** whet
24be0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 her or not it re
24bf0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 quires a protect
24c00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
24c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d ..**.** The term
24c20 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e s "protected" an
24c30 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 d "unprotected"
24c40 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 refer to whether
24c50 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 or not.** a mut
24c60 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 ex is held. An
24c70 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 internal mutex i
24c80 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f s held for a pro
24c90 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
24ca0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 3_value object b
24cb0 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 ut no mutex is h
24cc0 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f eld for an unpro
24cd0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
24ce0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 3_value object.
24cf0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f If SQLite is co
24d00 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e mpiled to be sin
24d10 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 gle-threaded.**
24d20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 (with [SQLITE_TH
24d30 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 READSAFE=0] and
24d40 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 with [sqlite3_th
24d50 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 readsafe()] retu
24d60 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 rning 0).** or i
24d70 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 f SQLite is run
24d80 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 in one of reduce
24d90 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a d mutex modes .*
24da0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
24db0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f _SINGLETHREAD] o
24dc0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
24dd0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a _MULTITHREAD].**
24de0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e then there is n
24df0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 o distinction be
24e00 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
24e10 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
24e20 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
24e30 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 objects and the
24e40 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e y can be used in
24e50 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 terchangeably.
24e60 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 However,.** for
24e70 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 maximum code por
24e80 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 tability it is r
24e90 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
24ea0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
24eb0 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 still make the d
24ec0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 istinction betwe
24ed0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
24ee0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
24ef0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
24f00 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 jects even when
24f10 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 not strictly req
24f20 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 uired..**.** ^Th
24f30 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
24f40 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 objects that are
24f50 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d passed as param
24f60 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a eters into the.*
24f70 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
24f80 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e of [application
24f90 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
24fa0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 ctions] are prot
24fb0 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 ected..** ^The s
24fc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
24fd0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
24fe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
24ff0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
25000 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 nprotected..** U
25010 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
25020 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
25030 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 may only be use
25040 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 d with.** [sqlit
25050 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
25060 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
25070 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a bind_value()]..*
25080 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 * The [sqlite3_v
25090 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 alue_blob | sqli
250a0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 te3_value_type()
250b0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 ] family of.** i
250c0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 nterfaces requir
250d0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 e protected sqli
250e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
250f0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 s..*/.typedef st
25100 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 ruct Mem sqlite3
25110 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _value;../*.** C
25120 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e API3REF: SQL Fun
25130 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 ction Context Ob
25140 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ject.**.** The c
25150 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 ontext in which
25160 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 an SQL function
25170 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 executes is stor
25180 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 ed in an.** sqli
25190 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
251a0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 ct. ^A pointer
251b0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f to an sqlite3_co
251c0 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 ntext object.**
251d0 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 is always first
251e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 parameter to [ap
251f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
25200 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
25210 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
25220 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
25230 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
25240 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 entation will pa
25250 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 ss this.** point
25260 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 er through into
25270 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
25280 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 3_result_int | s
25290 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d qlite3_result()]
252a0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 ,.** [sqlite3_ag
252b0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
252c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 )], [sqlite3_use
252d0 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 r_data()],.** [s
252e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
252f0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 b_handle()], [sq
25300 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
25310 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 a()],.** and/or
25320 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 [sqlite3_set_aux
25330 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 data()]..*/.type
25340 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
25350 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 e3_context sqlit
25360 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a e3_context;../*.
25370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e ** CAPI3REF: Bin
25380 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 ding Values To P
25390 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
253a0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ts.** KEYWORDS:
253b0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d {host parameter}
253c0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
253d0 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 s} {host paramet
253e0 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 er name}.** KEYW
253f0 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d ORDS: {SQL param
25400 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d eter} {SQL param
25410 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 eters} {paramete
25420 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a r binding}.**.**
25430 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 ^(In the SQL st
25440 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 atement text inp
25450 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 ut to [sqlite3_p
25460 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
25470 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a its variants,.*
25480 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 * literals may b
25490 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 e replaced by a
254a0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 [parameter] that
254b0 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 matches one of
254c0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d following.** tem
254d0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 plates:.**.** <u
254e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a l>.** <li> ?.**
254f0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c <li> ?NNN.** <
25500 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 li> :VVV.** <li
25510 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > @VVV.** <li>
25520 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a $VVV.** </ul>.*
25530 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 *.** In the temp
25540 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e lates above, NNN
25550 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 represents an i
25560 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a nteger literal,.
25570 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 ** and VVV repre
25580 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 sents an alphanu
25590 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 meric identifier
255a0 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 .)^ ^The values
255b0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 of these.** par
255c0 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 ameters (also ca
255d0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d lled "host param
255e0 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 eter names" or "
255f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 SQL parameters")
25600 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 .** can be set u
25610 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
25620 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
25630 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e es defined here.
25640 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
25650 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
25660 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
25670 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 () routines is a
25680 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 lways.** a point
25690 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
256a0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 e3_stmt] object
256b0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a returned from.**
256c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
256d0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 e_v2()] or its v
256e0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e ariants..**.** ^
256f0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
25700 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 ent is the index
25710 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 of the SQL para
25720 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e meter to be set.
25730 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 .** ^The leftmos
25740 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 t SQL parameter
25750 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 has an index of
25760 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 1. ^When the sa
25770 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 me named.** SQL
25780 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 parameter is use
25790 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 d more than once
257a0 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 , second and sub
257b0 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 sequent.** occur
257c0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 rences have the
257d0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 same index as th
257e0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e e first occurren
257f0 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 ce..** ^The inde
25800 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 x for named para
25810 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f meters can be lo
25820 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 oked up using th
25830 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 e.** [sqlite3_bi
25840 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
25850 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 ex()] API if des
25860 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 ired. ^The inde
25870 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 x.** for "?NNN"
25880 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 parameters is th
25890 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a e value of NNN..
258a0 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 ** ^The NNN valu
258b0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 e must be betwee
258c0 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c n 1 and the [sql
258d0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
258e0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 parameter [SQLI
258f0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
25900 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 E_NUMBER] (defau
25910 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a lt value: 999)..
25920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 **.** ^The third
25930 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
25940 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 value to bind t
25950 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e o the parameter.
25960 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 .**.** ^(In thos
25970 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 e routines that
25980 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
25990 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
259a0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
259b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
259c0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
259d0 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
259e0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
259f0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 number of <u>byt
25a00 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 es</u> in the va
25a10 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d lue, not the num
25a20 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
25a30 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 s.)^.** ^If the
25a40 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
25a50 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
25a60 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
25a70 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 string is.** the
25a80 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
25a90 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 up to the first
25aa0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
25ab0 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 ..** If a non-ne
25ac0 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 gative fourth pa
25ad0 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 rameter is provi
25ae0 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ded to sqlite3_b
25af0 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 ind_text().** or
25b00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
25b10 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 xt16() then that
25b20 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 parameter must
25b30 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 be the byte offs
25b40 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 et.** where the
25b50 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 NUL terminator w
25b60 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d ould occur assum
25b70 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 ing the string w
25b80 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 ere NUL.** termi
25b90 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e nated. If any N
25ba0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 UL characters oc
25bb0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 cur at byte offs
25bc0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a ets less than .*
25bd0 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 * the value of t
25be0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
25bf0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 ter then the res
25c00 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 ulting string va
25c10 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 lue will.** cont
25c20 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c ain embedded NUL
25c30 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f s. The result o
25c40 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e f expressions in
25c50 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a volving strings.
25c60 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 ** with embedded
25c70 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e NULs is undefin
25c80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
25c90 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f ifth argument to
25ca0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
25cb0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 ob(), sqlite3_bi
25cc0 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a nd_text(), and.*
25cd0 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 * sqlite3_bind_t
25ce0 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 ext16() is a des
25cf0 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 tructor used to
25d00 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 dispose of the B
25d10 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 LOB or.** string
25d20 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 after SQLite ha
25d30 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
25d40 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 it. ^The destru
25d50 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a ctor is called.*
25d60 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 * to dispose of
25d70 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 the BLOB or stri
25d80 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 ng even if the c
25d90 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 all to sqlite3_b
25da0 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 ind_blob(),.** s
25db0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
25dc0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 (), or sqlite3_b
25dd0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 ind_text16() fai
25de0 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 ls. .** ^If the
25df0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 fifth argument
25e00 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 is.** the specia
25e10 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f l value [SQLITE_
25e20 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 STATIC], then SQ
25e30 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 Lite assumes tha
25e40 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 t the.** informa
25e50 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 tion is in stati
25e60 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 c, unmanaged spa
25e70 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 ce and does not
25e80 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 need to be freed
25e90 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 ..** ^If the fif
25ea0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 th argument has
25eb0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 the value [SQLIT
25ec0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 E_TRANSIENT], th
25ed0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b en.** SQLite mak
25ee0 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 es its own priva
25ef0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 te copy of the d
25f00 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c ata immediately,
25f10 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 before.** the s
25f20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
25f30 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e routine returns.
25f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
25f50 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
25f60 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 b() routine bind
25f70 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 s a BLOB of leng
25f80 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 th N that.** is
25f90 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f filled with zero
25fa0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 es. ^A zeroblob
25fb0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d uses a fixed am
25fc0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a ount of memory.*
25fd0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 * (just an integ
25fe0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 er to hold its s
25ff0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 ize) while it is
26000 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 being processed
26010 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 ..** Zeroblobs a
26020 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 re intended to s
26030 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c erve as placehol
26040 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 ders for BLOBs w
26050 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 hose.** content
26060 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e is later written
26070 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
26080 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 e3_blob_open | i
26090 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 ncremental BLOB
260a0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a I/O] routines..*
260b0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 * ^A negative va
260c0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f lue for the zero
260d0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 blob results in
260e0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
260f0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e OB..**.** ^If an
26100 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 y of the sqlite3
26110 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
26120 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 es are called wi
26130 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
26140 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 r.** for the [pr
26150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
26160 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 ] or with a prep
26170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 ared statement f
26180 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c or which.** [sql
26190 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
261a0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 been called mor
261b0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 e recently than
261c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
261d0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 ],.** then the c
261e0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 all will return
261f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
26200 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 If any sqlite3
26210 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 _bind_().** rout
26220 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 ine is passed a
26230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26240 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 ent] that has be
26250 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 en finalized, th
26260 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 e.** result is u
26270 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
26280 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a bably harmful..*
26290 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 *.** ^Bindings a
262a0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 re not cleared b
262b0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 y the [sqlite3_r
262c0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e eset()] routine.
262d0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 .** ^Unbound par
262e0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 ameters are inte
262f0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e rpreted as NULL.
26300 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
26310 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 te3_bind_* routi
26320 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 nes return [SQLI
26330 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
26340 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f s or an.** [erro
26350 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 r code] if anyth
26360 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a ing goes wrong..
26370 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 ** ^[SQLITE_RANG
26380 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 E] is returned i
26390 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a f the parameter.
263a0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 ** index is out
263b0 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c of range. ^[SQL
263c0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 ITE_NOMEM] is re
263d0 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 turned if malloc
263e0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 () fails..**.**
263f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
26400 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
26410 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b r_count()],.** [
26420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
26430 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
26440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e and [sqlite3_bin
26450 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
26460 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c x()]..*/.int sql
26470 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 ite3_bind_blob(s
26480 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
26490 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
264a0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 int n, void(*)(v
264b0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 oid*));.int sqli
264c0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 te3_bind_double(
264d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
264e0 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 nt, double);.int
264f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e sqlite3_bind_in
26500 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
26510 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 int, int);.int
26520 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 sqlite3_bind_int
26530 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
26540 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 , int, sqlite3_i
26550 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 nt64);.int sqlit
26560 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c e3_bind_null(sql
26570 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
26580 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
26590 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f nd_text(sqlite3_
265a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
265b0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 t char*, int n,
265c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
265d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
265e0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 d_text16(sqlite3
265f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
26600 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
26610 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
26620 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
26630 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
26640 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
26650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 sqlite3_value*)
26660 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
26670 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 nd_zeroblob(sqli
26680 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
26690 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
266a0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
266b0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 Of SQL Parameter
266c0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f s.**.** ^This ro
266d0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 utine can be use
266e0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 d to find the nu
266f0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 mber of [SQL par
26700 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 ameters].** in a
26710 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26720 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 ment]. SQL para
26730 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e meters are token
26740 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d s of the.** form
26750 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a "?", "?NNN", ":
26760 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 AAA", "$AAA", or
26770 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 "@AAA" that ser
26780 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f ve as.** placeho
26790 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 lders for values
267a0 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 that are [sqlit
267b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
267c0 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 ound].** to the
267d0 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 parameters at a
267e0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a later time..**.*
267f0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 * ^(This routine
26800 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e actually return
26810 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
26820 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 he largest (righ
26830 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 tmost).** parame
26840 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 ter. For all for
26850 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 ms except ?NNN,
26860 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 this will corres
26870 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e pond to the.** n
26880 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 umber of unique
26890 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 parameters. If
268a0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
268b0 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 e ?NNN form are
268c0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d used,.** there m
268d0 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 ay be gaps in th
268e0 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 e list.)^.**.**
268f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
26900 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
26910 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a ite3_bind()],.**
26920 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
26930 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
26940 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
26950 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
26960 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e _index()]..*/.in
26970 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 t sqlite3_bind_p
26980 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 arameter_count(s
26990 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
269a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
269b0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 Name Of A Host P
269c0 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e arameter.**.** ^
269d0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
269e0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
269f0 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 P,N) interface r
26a00 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 eturns.** the na
26a10 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b me of the N-th [
26a20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 SQL parameter] i
26a30 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
26a40 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a statement] P..**
26a50 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ^(SQL parameter
26a60 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f s of the form "?
26a70 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f NNN" or ":AAA" o
26a80 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 r "@AAA" or "$AA
26a90 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d A".** have a nam
26aa0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 e which is the s
26ab0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 tring "?NNN" or
26ac0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 ":AAA" or "@AAA"
26ad0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 or "$AAA".** re
26ae0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 spectively..** I
26af0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
26b00 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f he initial ":" o
26b10 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 r "$" or "@" or
26b20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 "?".** is includ
26b30 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
26b40 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 e name.)^.** ^Pa
26b50 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
26b60 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 form "?" without
26b70 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 a following int
26b80 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d eger have no nam
26b90 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 e.** and are ref
26ba0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d erred to as "nam
26bb0 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 eless" or "anony
26bc0 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 mous parameters"
26bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
26be0 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 st host paramete
26bf0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f r has an index o
26c00 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a f 1, not 0..**.*
26c10 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 * ^If the value
26c20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 N is out of rang
26c30 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 e or if the N-th
26c40 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
26c50 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 nameless, then
26c60 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 NULL is returned
26c70 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 . ^The returned
26c80 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c string is.** al
26c90 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e ways in UTF-8 en
26ca0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 coding even if t
26cb0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 he named paramet
26cc0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e er was.** origin
26cd0 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 ally specified a
26ce0 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c s UTF-16 in [sql
26cf0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
26d00 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
26d10 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
26d20 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
26d30 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
26d40 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
26d50 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
26d60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
26d70 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a _count()], and.*
26d80 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
26d90 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
26da0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 )]..*/.const cha
26db0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f r *sqlite3_bind_
26dc0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 parameter_name(s
26dd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
26de0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
26df0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 REF: Index Of A
26e00 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 Parameter With A
26e10 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a Given Name.**.*
26e20 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e * ^Return the in
26e30 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 dex of an SQL pa
26e40 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 rameter given it
26e50 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a s name. ^The.**
26e60 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 index value ret
26e70 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c urned is suitabl
26e80 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 e for use as the
26e90 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d second.** param
26ea0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
26eb0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
26ec0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 e3_bind()]. ^A
26ed0 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 zero.** is retur
26ee0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 ned if no matchi
26ef0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 ng parameter is
26f00 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 found. ^The par
26f10 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d ameter.** name m
26f20 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 ust be given in
26f30 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 UTF-8 even if th
26f40 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 e original state
26f50 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 ment.** was prep
26f60 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 ared from UTF-16
26f70 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c text using [sql
26f80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
26f90 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 2()]..**.** See
26fa0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
26fb0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
26fc0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
26fd0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
26fe0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 eter_count()], a
26ff0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
27000 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
27010 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 dex()]..*/.int s
27020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
27030 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 meter_index(sqli
27040 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 te3_stmt*, const
27050 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a char *zName);..
27060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27070 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e Reset All Bindin
27080 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 gs On A Prepared
27090 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a Statement.**.**
270a0 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 ^Contrary to th
270b0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d e intuition of m
270c0 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 any, [sqlite3_re
270d0 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 set()] does not
270e0 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 reset.** the [sq
270f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
27100 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 | bindings] on a
27110 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
27120 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 ment]..** ^Use t
27130 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 his routine to r
27140 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 eset all host pa
27150 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c rameters to NULL
27160 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
27170 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
27180 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
27190 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
271a0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d Number Of Colum
271b0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 ns In A Result S
271c0 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e et.**.** ^Return
271d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
271e0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
271f0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 sult set returne
27200 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 d by the.** [pre
27210 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
27220 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 . ^This routine
27230 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 returns 0 if pSt
27240 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 mt is an SQL.**
27250 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 statement that d
27260 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 oes not return d
27270 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ata (for example
27280 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a an [UPDATE])..*
27290 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
272a0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
272b0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c nt()].*/.int sql
272c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
272d0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
272e0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
272f0 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 API3REF: Column
27300 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c Names In A Resul
27310 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 t Set.**.** ^The
27320 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
27330 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 rn the name assi
27340 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 gned to a partic
27350 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 ular column.** i
27360 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 n the result set
27370 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 of a [SELECT] s
27380 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 tatement. ^The
27390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
273a0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 ame().** interfa
273b0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
273c0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
273d0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
273e0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 string.** and sq
273f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
27400 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 e16() returns a
27410 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
27420 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
27430 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 UTF-16 string.
27440 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d ^The first param
27450 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 eter is the [pre
27460 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
27470 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 .** that impleme
27480 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d nts the [SELECT]
27490 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 statement. ^The
274a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
274b0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 r is the.** colu
274c0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 mn number. ^The
274d0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e leftmost column
274e0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a is number 0..**
274f0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 .** ^The returne
27500 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 d string pointer
27510 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
27520 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 either the [prep
27530 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
27540 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 ** is destroyed
27550 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 by [sqlite3_fina
27560 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c lize()] or until
27570 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
27580 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a s automatically.
27590 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 ** reprepared by
275a0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 the first call
275b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
275c0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 ()] for a partic
275d0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 ular run.** or u
275e0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 ntil the next ca
275f0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
27600 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f _column_name() o
27610 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
27620 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 _name16() on the
27630 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a same column..**
27640 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
27650 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 malloc() fails d
27660 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 uring the proces
27670 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 sing of either r
27680 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 outine.** (for e
27690 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 xample during a
276a0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 conversion from
276b0 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 UTF-8 to UTF-16)
276c0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 then a.** NULL
276d0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
276e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
276f0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 name of a result
27700 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 column is the v
27710 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 alue of the "AS"
27720 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 clause for.** t
27730 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 hat column, if t
27740 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c here is an AS cl
27750 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 ause. If there
27760 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a is no AS clause.
27770 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 ** then the name
27780 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 of the column i
27790 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e s unspecified an
277a0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f d may change fro
277b0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 m.** one release
277c0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 of SQLite to th
277d0 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 e next..*/.const
277e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
277f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 olumn_name(sqlit
27800 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 e3_stmt*, int N)
27810 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
27820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
27830 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
27840 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a *, int N);../*.*
27850 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 * CAPI3REF: Sour
27860 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 ce Of Data In A
27870 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a Query Result.**.
27880 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
27890 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 es provide a mea
278a0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ns to determine
278b0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 the database, ta
278c0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c ble, and.** tabl
278d0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 e column that is
278e0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 the origin of a
278f0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 particular resu
27900 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 lt column in.**
27910 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
27920 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 nt..** ^The name
27930 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
27940 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c or table or col
27950 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 umn can be retur
27960 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 ned as.** either
27970 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d a UTF-8 or UTF-
27980 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 16 string. ^The
27990 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 _database_ rout
279a0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 ines return.** t
279b0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 he database name
279c0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f , the _table_ ro
279d0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
279e0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e e table name, an
279f0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f d.** the origin_
27a00 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
27a10 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 the column name
27a20 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e ..** ^The return
27a30 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c ed string is val
27a40 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 id until the [pr
27a50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27a60 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a ] is destroyed.*
27a70 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
27a80 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
27a90 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d until the statem
27aa0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ent is automatic
27ab0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 ally.** reprepar
27ac0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
27ad0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
27ae0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 _step()] for a p
27af0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a articular run.**
27b00 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 or until the sa
27b10 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 me information i
27b20 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 s requested.** a
27b30 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 gain in a differ
27b40 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a ent encoding..**
27b50 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 .** ^The names r
27b60 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 eturned are the
27b70 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 original un-alia
27b80 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 sed names of the
27b90 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 .** database, ta
27ba0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e ble, and column.
27bb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
27bc0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
27bd0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 ese interfaces i
27be0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
27bf0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 atement]..** ^Th
27c00 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
27c10 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
27c20 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 about the Nth r
27c30 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 esult column ret
27c40 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 urned by.** the
27c50 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 statement, where
27c60 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
27c70 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
27c80 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 nt..** ^The left
27c90 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 -most column is
27ca0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 column 0 for the
27cb0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
27cc0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 ** ^If the Nth c
27cd0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 olumn returned b
27ce0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 y the statement
27cf0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e is an expression
27d00 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 or.** subquery
27d10 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c and is not a col
27d20 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 umn value, then
27d30 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e all of these fun
27d40 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a ctions return.**
27d50 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 NULL. ^These r
27d60 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 outine might als
27d70 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 o return NULL if
27d80 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
27d90 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 tion error.** oc
27da0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 curs. ^Otherwis
27db0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 e, they return t
27dc0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 he name of the a
27dd0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
27de0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 , table,.** or c
27df0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 olumn that query
27e00 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 result column w
27e10 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f as extracted fro
27e20 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 m..**.** ^As wit
27e30 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 h all other SQLi
27e40 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 te APIs, those w
27e50 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 hose names end w
27e60 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a ith "16" return.
27e70 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 ** UTF-16 encode
27e80 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 d strings and th
27e90 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e e other function
27ea0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a s return UTF-8..
27eb0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 **.** ^These API
27ec0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c s are only avail
27ed0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
27ee0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
27ef0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
27f00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 LITE_ENABLE_COLU
27f10 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 MN_METADATA] C-p
27f20 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
27f30 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f ol..**.** If two
27f40 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
27f50 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
27f60 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
27f70 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 nes against the
27f80 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 same.** prepared
27f90 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 statement and c
27fa0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d olumn at the sam
27fb0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
27fc0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 results are.** u
27fd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
27fe0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
27ff0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
28000 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 or more.** [sqli
28010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
28020 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d ase_name | colum
28030 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 n metadata inter
28040 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 faces].** for th
28050 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 e same [prepared
28060 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 statement] and
28070 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a result column.**
28080 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
28090 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c e then the resul
280a0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
280b0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
280c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
280d0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 database_name(sq
280e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
280f0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
28100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
28110 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c abase_name16(sql
28120 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
28130 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
28140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
28150 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 e_name(sqlite3_s
28160 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 tmt*,int);.const
28170 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
28180 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
28190 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
281a0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 ,int);.const cha
281b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
281c0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 n_origin_name(sq
281d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
281e0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
281f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
28200 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 gin_name16(sqlit
28210 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a e3_stmt*,int);..
28220 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
28230 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 Declared Datatyp
28240 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 e Of A Query Res
28250 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ult.**.** ^(The
28260 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
28270 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
28280 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 tatement]..** If
28290 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 this statement
282a0 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 is a [SELECT] st
282b0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 atement and the
282c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 Nth column of th
282d0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 e.** returned re
282e0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 sult set of that
282f0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 [SELECT] is a t
28300 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 able column (not
28310 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f an.** expressio
28320 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 n or subquery) t
28330 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 hen the declared
28340 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 type of the tab
28350 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 le.** column is
28360 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 returned.)^ ^If
28370 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
28380 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
28390 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 t is an.** expre
283a0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 ssion or subquer
283b0 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 y, then a NULL p
283c0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
283d0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 ed..** ^The retu
283e0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 rned string is a
283f0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f lways UTF-8 enco
28400 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 ded..**.** ^(For
28410 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 example, given
28420 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 the database sch
28430 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 ema:.**.** CREAT
28440 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 E TABLE t1(c1 VA
28450 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e RIANT);.**.** an
28460 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 d the following
28470 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
28480 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 compiled:.**.**
28490 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 SELECT c1 + 1, c
284a0 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 1 FROM t1;.**.**
284b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f this routine wo
284c0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 uld return the s
284d0 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 tring "VARIANT"
284e0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 for the second r
284f0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 esult.** column
28500 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 (i==1), and a NU
28510 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 LL pointer for t
28520 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 he first result
28530 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e column (i==0).)^
28540 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 .**.** ^SQLite u
28550 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d ses dynamic run-
28560 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 time typing. ^S
28570 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 o just because a
28580 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 column.** is de
28590 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 clared to contai
285a0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 n a particular t
285b0 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 ype does not mea
285c0 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 n that the.** da
285d0 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 ta stored in tha
285e0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 t column is of t
285f0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
28600 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 . SQLite is.**
28610 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 strongly typed,
28620 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 but the typing i
28630 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 s dynamic not st
28640 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 atic. ^Type.**
28650 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 is associated wi
28660 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 th individual va
28670 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 lues, not with t
28680 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a he containers.**
28690 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 used to hold th
286a0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 ose values..*/.c
286b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
286c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
286d0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a pe(sqlite3_stmt*
286e0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
286f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
28700 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c n_decltype16(sql
28710 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
28720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
28730 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 : Evaluate An SQ
28740 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a L Statement.**.*
28750 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 * After a [prepa
28760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 red statement] h
28770 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 as been prepared
28780 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a using either.**
28790 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
287a0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
287b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
287c0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 ()] or one of th
287d0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 e legacy.** inte
287e0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f rfaces [sqlite3_
287f0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 prepare()] or [s
28800 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
28810 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 ()], this functi
28820 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 on.** must be ca
28830 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 lled one or more
28840 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 times to evalua
28850 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 te the statement
28860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 ..**.** The deta
28870 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 ils of the behav
28880 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ior of the sqlit
28890 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 e3_step() interf
288a0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e ace depend.** on
288b0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 whether the sta
288c0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 tement was prepa
288d0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 red using the ne
288e0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 wer "v2" interfa
288f0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ce.** [sqlite3_p
28900 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
28910 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
28920 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 e16_v2()] or the
28930 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a older legacy.**
28940 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 interface [sqli
28950 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
28960 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
28970 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 are16()]. The u
28980 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 se of the.** new
28990 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 "v2" interface
289a0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 is recommended f
289b0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 or new applicati
289c0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 ons but the lega
289d0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
289e0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f will continue to
289f0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a be supported..*
28a00 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 *.** ^In the leg
28a10 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
28a20 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
28a30 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b will be either [
28a40 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a SQLITE_BUSY],.**
28a50 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 [SQLITE_DONE],
28a60 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 [SQLITE_ROW], [S
28a70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 QLITE_ERROR], or
28a80 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
28a90 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 ..** ^With the "
28aa0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 v2" interface, a
28ab0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 ny of the other
28ac0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f [result codes] o
28ad0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 r.** [extended r
28ae0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 esult codes] mig
28af0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 ht be returned a
28b00 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b s well..**.** ^[
28b10 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 SQLITE_BUSY] mea
28b20 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 ns that the data
28b30 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 base engine was
28b40 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 unable to acquir
28b50 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 e the.** databas
28b60 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 e locks it needs
28b70 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 to do its job.
28b80 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 ^If the stateme
28b90 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d nt is a [COMMIT]
28ba0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 .** or occurs ou
28bb0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c tside of an expl
28bc0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
28bd0 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 , then you can r
28be0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 etry the.** stat
28bf0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 ement. If the s
28c00 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 tatement is not
28c10 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f a [COMMIT] and o
28c20 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a ccurs within an.
28c30 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e ** explicit tran
28c40 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 saction then you
28c50 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b should rollback
28c60 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
28c70 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 before.** conti
28c80 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 nuing..**.** ^[S
28c90 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e QLITE_DONE] mean
28ca0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 s that the state
28cb0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 ment has finishe
28cc0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 d executing.** s
28cd0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 uccessfully. sq
28ce0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
28cf0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
28d00 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 d again on this
28d10 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 virtual.** machi
28d20 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 ne without first
28d30 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
28d40 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 3_reset()] to re
28d50 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a set the virtual.
28d60 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 ** machine back
28d70 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 to its initial s
28d80 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 tate..**.** ^If
28d90 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
28da0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 t being executed
28db0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 returns any dat
28dc0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f a, then [SQLITE_
28dd0 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 ROW].** is retur
28de0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 ned each time a
28df0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 new row of data
28e00 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f is ready for pro
28e10 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a cessing by the.*
28e20 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 * caller. The va
28e30 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 lues may be acce
28e40 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b ssed using the [
28e50 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
28e60 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c nctions]..** sql
28e70 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 ite3_step() is c
28e80 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 alled again to r
28e90 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 etrieve the next
28ea0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a row of data..**
28eb0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 .** ^[SQLITE_ERR
28ec0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 OR] means that a
28ed0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 run-time error
28ee0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 (such as a const
28ef0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 raint.** violati
28f00 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 on) has occurred
28f10 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
28f20 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
28f30 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a called again on.
28f40 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 ** the VM. More
28f50 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 information may
28f60 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c be found by call
28f70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 ing [sqlite3_err
28f80 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 msg()]..** ^With
28f90 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
28fa0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 rface, a more sp
28fb0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
28fc0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a e (for example,.
28fd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 ** [SQLITE_INTER
28fe0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 RUPT], [SQLITE_S
28ff0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f CHEMA], [SQLITE_
29000 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f CORRUPT], and so
29010 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 forth).** can b
29020 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 e obtained by ca
29030 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
29040 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a eset()] on the.*
29050 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
29060 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 ement]. ^In the
29070 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
29080 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 .** the more spe
29090 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
290a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 is returned dir
290b0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 ectly by sqlite3
290c0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b _step()..**.** [
290d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d SQLITE_MISUSE] m
290e0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 eans that the th
290f0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 is routine was c
29100 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 alled inappropri
29110 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 ately..** Perhap
29120 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 s it was called
29130 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
29140 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
29150 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 as.** already be
29160 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 en [sqlite3_fina
29170 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 lize | finalized
29180 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 ] or on one that
29190 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 had.** previous
291a0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c ly returned [SQL
291b0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 ITE_ERROR] or [S
291c0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 QLITE_DONE]. Or
291d0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 it could.** be
291e0 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
291f0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
29200 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 connection is be
29210 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 ing used by two
29220 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 or.** more threa
29230 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d ds at the same m
29240 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a oment in time..*
29250 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 *.** For all ver
29260 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
29270 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 up to and includ
29280 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 ing 3.6.23.1, a
29290 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
292a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 te3_reset()] was
292b0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 required after
292c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 sqlite3_step() r
292d0 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 eturned anything
292e0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b .** other than [
292f0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f SQLITE_ROW] befo
29300 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e re any subsequen
29310 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a t invocation of.
29320 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
29330 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 ). Failure to r
29340 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
29350 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e d statement usin
29360 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 g .** [sqlite3_r
29370 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 eset()] would re
29380 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 sult in an [SQLI
29390 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 TE_MISUSE] retur
293a0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 n from.** sqlite
293b0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 3_step(). But a
293c0 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 fter version 3.6
293d0 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 .23.1, sqlite3_s
293e0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 tep() began.** c
293f0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
29400 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 reset()] automat
29410 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 ically in this c
29420 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 ircumstance rath
29430 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 er.** than retur
29440 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 ning [SQLITE_MIS
29450 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e USE]. This is n
29460 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 ot considered a
29470 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a compatibility.**
29480 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 break because a
29490 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ny application t
294a0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 hat ever receive
294b0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 s an SQLITE_MISU
294c0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 SE error.** is b
294d0 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 roken by definit
294e0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ion. The [SQLIT
294f0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 E_OMIT_AUTORESET
29500 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
29510 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 ption.** can be
29520 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 used to restore
29530 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 the legacy behav
29540 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f ior..**.** <b>Go
29550 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c ofy Interface Al
29560 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 ert:</b> In the
29570 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
29580 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 , the sqlite3_st
29590 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 ep().** API alwa
295a0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e ys returns a gen
295b0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c eric error code,
295c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
295d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a following any.*
295e0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 * error other th
295f0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d an [SQLITE_BUSY]
29600 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 and [SQLITE_MIS
29610 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 USE]. You must
29620 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 call.** [sqlite3
29630 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
29640 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
29650 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 ] in order to fi
29660 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a nd one of the.**
29670 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
29680 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 codes] that bet
29690 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 ter describes th
296a0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 e error..** We a
296b0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 dmit that this i
296c0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e s a goofy design
296d0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 . The problem h
296e0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a as been fixed.**
296f0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 with the "v2" i
29700 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f nterface. If yo
29710 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 u prepare all of
29720 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d your SQL statem
29730 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 ents.** using ei
29740 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
29750 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b epare_v2()] or [
29760 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
29770 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 6_v2()] instead.
29780 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 ** of the legacy
29790 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
297a0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
297b0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 3_prepare16()] i
297c0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 nterfaces,.** th
297d0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 en the more spec
297e0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 ific [error code
297f0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 s] are returned
29800 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 directly.** by s
29810 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
29820 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 The use of the "
29830 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 v2" interface is
29840 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f recommended..*/
29850 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 .int sqlite3_ste
29860 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 p(sqlite3_stmt*)
29870 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
29880 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c F: Number of col
29890 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 umns in a result
298a0 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 set.**.** ^The
298b0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
298c0 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 nt(P) interface
298d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
298e0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
298f0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 the.** current
29900 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
29910 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 t set of [prepar
29920 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
29930 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 .** ^If prepared
29940 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 statement P doe
29950 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c s not have resul
29960 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 ts ready to retu
29970 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 rn.** (via calls
29980 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
29990 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 _column_int | sq
299a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 lite3_column_*()
299b0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 ] of.** interfac
299c0 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 es) then sqlite3
299d0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 _data_count(P) r
299e0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 eturns 0..** ^Th
299f0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
29a00 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
29a10 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 also returns 0 i
29a20 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f P is a NULL po
29a30 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 inter..** ^The s
29a40 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
29a50 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 t(P) routine ret
29a60 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 urns 0 if the pr
29a70 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a evious call to.*
29a80 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d * [sqlite3_step]
29a90 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 (P) returned [SQ
29aa0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 LITE_DONE]. ^Th
29ab0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
29ac0 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 ount(P).** will
29ad0 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 return non-zero
29ae0 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c if previous call
29af0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
29b00 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a p](P) returned.*
29b10 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 * [SQLITE_ROW],
29b20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 except in the ca
29b30 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d se of the [PRAGM
29b40 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 A incremental_va
29b50 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 cuum].** where i
29b60 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 t always returns
29b70 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 zero since each
29b80 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 step of that mu
29b90 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 lti-step.** prag
29ba0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c ma returns 0 col
29bb0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a umns of data..**
29bc0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
29bd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
29be0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 unt()].*/.int sq
29bf0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
29c00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
29c10 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
29c20 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e PI3REF: Fundamen
29c30 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a tal Datatypes.**
29c40 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 KEYWORDS: SQLIT
29c50 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 E_TEXT.**.** ^(E
29c60 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 very value in SQ
29c70 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 Lite has one of
29c80 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c five fundamental
29c90 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a datatypes:.**.*
29ca0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 * <ul>.** <li> 6
29cb0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
29cc0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d eger.** <li> 64-
29cd0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e bit IEEE floatin
29ce0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a g point number.*
29cf0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a * <li> string.**
29d00 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c <li> BLOB.** <l
29d10 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e i> NULL.** </ul>
29d20 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 )^.**.** These c
29d30 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 onstants are cod
29d40 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 es for each of t
29d50 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a hose types..**.*
29d60 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 * Note that the
29d70 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 SQLITE_TEXT cons
29d80 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 tant was also us
29d90 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 ed in SQLite ver
29da0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 sion 2.** for a
29db0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 completely diffe
29dc0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 rent meaning. S
29dd0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e oftware that lin
29de0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a ks against both.
29df0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f ** SQLite versio
29e00 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 n 2 and SQLite v
29e10 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 ersion 3 should
29e20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 use SQLITE3_TEXT
29e30 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f , not.** SQLITE_
29e40 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 TEXT..*/.#define
29e50 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 SQLITE_INTEGER
29e60 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
29e70 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 E_FLOAT 2.#de
29e80 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 fine SQLITE_BLOB
29e90 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
29ea0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 QLITE_NULL 5
29eb0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 .#ifdef SQLITE_T
29ec0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 EXT.# undef SQLI
29ed0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 TE_TEXT.#else.#
29ee0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
29ef0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a XT 3.#endif.
29f00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f #define SQLITE3_
29f10 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a TEXT 3../*.*
29f20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 * CAPI3REF: Resu
29f30 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 lt Values From A
29f40 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 Query.** KEYWOR
29f50 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 DS: {column acce
29f60 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a ss functions}.**
29f70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
29f80 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 es form the "res
29f90 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 ult set" interfa
29fa0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ce..**.** ^These
29fb0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
29fc0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
29fd0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 ut a single colu
29fe0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e mn of the curren
29ff0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 t.** result row
2a000 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e of a query. ^In
2a010 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 every case the
2a020 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
2a030 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 s a pointer.** t
2a040 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 o the [prepared
2a050 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
2a060 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 is being evaluat
2a070 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 ed (the [sqlite3
2a080 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 _stmt*].** that
2a090 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f was returned fro
2a0a0 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 m [sqlite3_prepa
2a0b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 re_v2()] or one
2a0c0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 of its variants)
2a0d0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f .** and the seco
2a0e0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
2a0f0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
2a100 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 column for which
2a110 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
2a120 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e should be return
2a130 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 ed. ^The leftmos
2a140 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 t column of the
2a150 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 result set has t
2a160 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e he index 0..** ^
2a170 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f The number of co
2a180 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
2a190 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 ult can be deter
2a1a0 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b mined using.** [
2a1b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
2a1c0 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 ount()]..**.** I
2a1d0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
2a1e0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 ent does not cur
2a1f0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 rently point to
2a200 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 a valid row, or
2a210 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e if the.** column
2a220 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 index is out of
2a230 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 range, the resu
2a240 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e lt is undefined.
2a250 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
2a260 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 es may only be c
2a270 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d alled when the m
2a280 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
2a290 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 to.** [sqlite3_s
2a2a0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 tep()] has retur
2a2b0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d ned [SQLITE_ROW]
2a2c0 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 and neither.**
2a2d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2a2e0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 ] nor [sqlite3_f
2a2f0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 inalize()] have
2a300 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 been called subs
2a310 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 equently..** If
2a320 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 any of these rou
2a330 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
2a340 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f after [sqlite3_
2a350 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b reset()] or.** [
2a360 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2a370 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 ()] or after [sq
2a380 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
2a390 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f s returned.** so
2a3a0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 mething other th
2a3b0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c an [SQLITE_ROW],
2a3c0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
2a3d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 undefined..** I
2a3e0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 f [sqlite3_step(
2a3f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
2a400 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 eset()] or [sqli
2a410 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a te3_finalize()].
2a420 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 ** are called fr
2a430 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 om a different t
2a440 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 hread while any
2a450 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
2a460 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 s.** are pending
2a470 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c , then the resul
2a480 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
2a490 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2a4a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
2a4b0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
2a4c0 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 ns the.** [SQLIT
2a4d0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 E_INTEGER | data
2a4e0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 type code] for t
2a4f0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 he initial data
2a500 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 type.** of the r
2a510 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e esult column. ^
2a520 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c The returned val
2a530 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 ue is one of [SQ
2a540 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a LITE_INTEGER],.*
2a550 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d * [SQLITE_FLOAT]
2a560 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c , [SQLITE_TEXT],
2a570 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 [SQLITE_BLOB],
2a580 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d or [SQLITE_NULL]
2a590 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 . The value.**
2a5a0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
2a5b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2a5c0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e ) is only meanin
2a5d0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a gful if no type.
2a5e0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 ** conversions h
2a5f0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 ave occurred as
2a600 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e described below.
2a610 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 After a type c
2a620 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 onversion,.** th
2a630 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
2a640 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
2a650 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 mn_type() is und
2a660 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a efined. Future.
2a670 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 ** versions of S
2a680 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 QLite may change
2a690 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
2a6a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2a6b0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 type().** follow
2a6c0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 ing a type conve
2a6d0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 rsion..**.** ^If
2a6e0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
2a6f0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 BLOB or UTF-8 s
2a700 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 tring then the s
2a710 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2a720 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 tes().** routine
2a730 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
2a740 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2a750 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 that BLOB or str
2a760 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
2a770 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d result is a UTF-
2a780 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 16 string, then
2a790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2a7a0 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a ytes() converts.
2a7b0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f ** the string to
2a7c0 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 UTF-8 and then
2a7d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2a7e0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 er of bytes..**
2a7f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2a800 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 s a numeric valu
2a810 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 e then sqlite3_c
2a820 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 olumn_bytes() us
2a830 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 es.** [sqlite3_s
2a840 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f nprintf()] to co
2a850 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 nvert that value
2a860 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 to a UTF-8 stri
2a870 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a ng and returns.*
2a880 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
2a890 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 bytes in that st
2a8a0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
2a8b0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c result is NULL,
2a8c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
2a8d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 lumn_bytes() ret
2a8e0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a urns zero..**.**
2a8f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
2a900 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 is a BLOB or UTF
2a910 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 -16 string then
2a920 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
2a930 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 mn_bytes16().**
2a940 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
2a950 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2a960 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 tes in that BLOB
2a970 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e or string..** ^
2a980 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
2a990 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c a UTF-8 string,
2a9a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
2a9b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 lumn_bytes16() c
2a9c0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 onverts.** the s
2a9d0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 tring to UTF-16
2a9e0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 and then returns
2a9f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2aa00 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ytes..** ^If the
2aa10 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d result is a num
2aa20 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 eric value then
2aa30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2aa40 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a ytes16() uses.**
2aa50 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
2aa60 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 tf()] to convert
2aa70 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 that value to a
2aa80 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 UTF-16 string a
2aa90 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 nd returns.** th
2aaa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2aab0 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 s in that string
2aac0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
2aad0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ult is NULL, the
2aae0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
2aaf0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 _bytes16() retur
2ab00 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e ns zero..**.** ^
2ab10 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 The values retur
2ab20 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
2ab30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 column_bytes()]
2ab40 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and .** [sqlite3
2ab50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2ab60 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 )] do not includ
2ab70 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 e the zero termi
2ab80 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e nators at the en
2ab90 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 d.** of the stri
2aba0 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 ng. ^For clarit
2abb0 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 y: the values re
2abc0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
2abd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2abe0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 es()] and [sqlit
2abf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2ac00 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 6()] are the num
2ac10 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 ber of.** bytes
2ac20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e in the string, n
2ac30 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
2ac40 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
2ac50 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 ** ^Strings retu
2ac60 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
2ac70 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e column_text() an
2ac80 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2ac90 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 _text16(),.** ev
2aca0 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 en empty strings
2acb0 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 , are always zer
2acc0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e o-terminated. ^
2acd0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 The return.** va
2ace0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
2acf0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 _column_blob() f
2ad00 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 or a zero-length
2ad10 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 BLOB is a NULL
2ad20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
2ad30 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 The object retur
2ad40 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
2ad50 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
2ad60 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 is an.** [unprot
2ad70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2ad80 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e lue] object. An
2ad90 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
2ada0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2adb0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 t.** may only be
2adc0 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 used with [sqli
2add0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 te3_bind_value()
2ade0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
2adf0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a esult_value()]..
2ae00 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f ** If the [unpro
2ae10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2ae20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 alue] object ret
2ae30 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
2ae40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
2ae50 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 e()] is used in
2ae60 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 any other way, i
2ae70 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a ncluding calls.*
2ae80 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 * to routines li
2ae90 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ke [sqlite3_valu
2aea0 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 e_int()], [sqlit
2aeb0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
2aec0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ,.** or [sqlite3
2aed0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c _value_bytes()],
2aee0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
2aef0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
2af00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
2af10 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f tines attempt to
2af20 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c convert the val
2af30 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 ue where appropr
2af40 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 iate. ^For.** e
2af50 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 xample, if the i
2af60 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e nternal represen
2af70 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 tation is FLOAT
2af80 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c and a text resul
2af90 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 t.** is requeste
2afa0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 d, [sqlite3_snpr
2afb0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 intf()] is used
2afc0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 internally to pe
2afd0 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e rform the.** con
2afe0 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 version automati
2aff0 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f cally. ^(The fo
2b000 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 llowing table de
2b010 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 tails the conver
2b020 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 sions.** that ar
2b030 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a e applied:.**.**
2b040 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a <blockquote>.**
2b050 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 <table border="
2b060 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 1">.** <tr><th>
2b070 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 Internal<br>Type
2b080 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c <th> Requested<
2b090 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f br>Type <th> Co
2b0a0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c nversion.**.** <
2b0b0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
2b0c0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
2b0d0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
2b0e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
2b0f0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 LL <td> FLOA
2b100 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 T <td> Result
2b110 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c is 0.0.** <tr><
2b120 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
2b130 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2b140 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 Result is NULL
2b150 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
2b160 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
2b170 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
2b180 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 Result is NULL
2b190 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
2b1a0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
2b1b0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
2b1c0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e Convert from in
2b1d0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a teger to float.*
2b1e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
2b1f0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 ER <td> TEXT
2b200 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
2b210 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 ndering of the i
2b220 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 nteger.** <tr><t
2b230 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
2b240 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
2b250 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d Same as INTEGER-
2b260 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 >TEXT.** <tr><td
2b270 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
2b280 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 INTEGER <td> C
2b290 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 onvert from floa
2b2a0 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 t to integer.**
2b2b0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
2b2c0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
2b2d0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 <td> ASCII rend
2b2e0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f ering of the flo
2b2f0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 at.** <tr><td>
2b300 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 FLOAT <td> B
2b310 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 LOB <td> Same
2b320 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a as FLOAT->TEXT.
2b330 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 ** <tr><td> TEX
2b340 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 T <td> INTEGE
2b350 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f R <td> Use ato
2b360 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 i().** <tr><td>
2b370 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 TEXT <td> F
2b380 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 LOAT <td> Use
2b390 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c atof().** <tr><
2b3a0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
2b3b0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
2b3c0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 No change.** <t
2b3d0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
2b3e0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
2b3f0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 td> Convert to T
2b400 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f EXT then use ato
2b410 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 i().** <tr><td>
2b420 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 BLOB <td> F
2b430 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e LOAT <td> Con
2b440 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 vert to TEXT the
2b450 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 n use atof().**
2b460 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
2b470 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
2b480 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f <td> Add a zero
2b490 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e terminator if n
2b4a0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 eeded.** </table
2b4b0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 >.** </blockquot
2b4c0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 e>)^.**.** The t
2b4d0 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 able above makes
2b4e0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 reference to st
2b4f0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
2b500 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 functions atoi(
2b510 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e ).** and atof().
2b520 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f SQLite does no
2b530 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 t really use the
2b540 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 se functions. I
2b550 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e t has its.** own
2b560 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 equivalent inte
2b570 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 rnal routines.
2b580 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 The atoi() and a
2b590 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a tof() names are.
2b5a0 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 ** used in the t
2b5b0 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 able for brevity
2b5c0 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 and because the
2b5d0 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 y are familiar t
2b5e0 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 o most.** C prog
2b5f0 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e rammers..**.** N
2b600 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 ote that when ty
2b610 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f pe conversions o
2b620 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 ccur, pointers r
2b630 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 eturned by prior
2b640 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c .** calls to sql
2b650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
2b660 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 (), sqlite3_colu
2b670 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f mn_text(), and/o
2b680 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
2b690 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 umn_text16() may
2b6a0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e be invalidated.
2b6b0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 .** Type convers
2b6c0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 ions and pointer
2b6d0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d invalidations m
2b6e0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e ight occur.** in
2b6f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 the following c
2b700 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ases:.**.** <ul>
2b710 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
2b720 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
2b730 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 a BLOB and sqlit
2b740 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2b750 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
2b760 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2b770 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
2b780 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f A zero-terminato
2b790 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 r might.**
2b7a0 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 need to be added
2b7b0 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c to the string.<
2b7c0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
2b7d0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
2b7e0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 is UTF-8 text a
2b7f0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
2b800 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a n_bytes16() or.*
2b810 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
2b820 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 olumn_text16() i
2b830 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 s called. The c
2b840 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 ontent must be c
2b850 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 onverted.**
2b860 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e to UTF-16.</li>
2b870 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
2b880 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
2b890 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 UTF-16 text and
2b8a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2b8b0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 ytes() or.**
2b8c0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
2b8d0 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 _text() is calle
2b8e0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 d. The content
2b8f0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
2b900 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 d.** to UTF
2b910 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c -8.</li>.** </ul
2b920 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 >.**.** ^Convers
2b930 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 ions between UTF
2b940 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 -16be and UTF-16
2b950 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f le are always do
2b960 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 ne in place and
2b970 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 do.** not invali
2b980 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 date a prior poi
2b990 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 nter, though of
2b9a0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 course the conte
2b9b0 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 nt of the buffer
2b9c0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 .** that the pri
2b9d0 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 or pointer refer
2b9e0 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 ences will have
2b9f0 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 been modified.
2ba00 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f Other kinds.** o
2ba10 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 f conversion are
2ba20 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 done in place w
2ba30 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 hen it is possib
2ba40 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 le, but sometime
2ba50 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f s they.** are no
2ba60 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 t possible and i
2ba70 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 n those cases pr
2ba80 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 ior pointers are
2ba90 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a invalidated..**
2baa0 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 .** The safest a
2bab0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 nd easiest to re
2bac0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 member policy is
2bad0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 to invoke these
2bae0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 routines.** in
2baf0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
2bb00 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a wing ways:.**.**
2bb10 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 <ul>.** <li>sq
2bb20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2bb30 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 t() followed by
2bb40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2bb50 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
2bb60 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
2bb70 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 mn_blob() follow
2bb80 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
2bb90 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
2bba0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
2bbb0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2bbc0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
2bbd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2bbe0 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c es16()</li>.** <
2bbf0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 /ul>.**.** In ot
2bc00 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 her words, you s
2bc10 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 hould call sqlit
2bc20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2bc30 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c ,.** sqlite3_col
2bc40 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 umn_blob(), or s
2bc50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2bc60 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 xt16() first to
2bc70 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 force the result
2bc80 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 .** into the des
2bc90 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 ired format, the
2bca0 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 n invoke sqlite3
2bcb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2bcc0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
2bcd0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 lumn_bytes16() t
2bce0 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 o find the size
2bcf0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 of the result.
2bd00 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 Do not mix calls
2bd10 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
2bd20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 olumn_text() or
2bd30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2bd40 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 lob() with calls
2bd50 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
2bd60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c olumn_bytes16(),
2bd70 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 and do not mix
2bd80 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
2bd90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2bda0 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 .** with calls t
2bdb0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
2bdc0 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 _bytes()..**.**
2bdd0 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 ^The pointers re
2bde0 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 turned are valid
2bdf0 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f until a type co
2be00 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 nversion occurs
2be10 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 as.** described
2be20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 above, or until
2be30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2be40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
2be50 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
2be60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
2be70 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 is called. ^Th
2be80 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 e memory space u
2be90 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 sed to hold stri
2bea0 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 ngs.** and BLOBs
2beb0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 is freed automa
2bec0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e tically. Do <b>
2bed0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 not</b> pass the
2bee0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
2bef0 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ed.** [sqlite3_c
2bf00 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b olumn_blob()], [
2bf10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2bf20 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 ext()], etc. int
2bf30 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 o.** [sqlite3_fr
2bf40 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 ee()]..**.** ^(I
2bf50 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
2bf60 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 ation error occu
2bf70 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 rs during the ev
2bf80 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a aluation of any.
2bf90 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ** of these rout
2bfa0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 ines, a default
2bfb0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 value is returne
2bfc0 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 d. The default
2bfd0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 value.** is eith
2bfe0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 er the integer 0
2bff0 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 , the floating p
2c000 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c oint number 0.0,
2c010 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f or a NULL.** po
2c020 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 inter. Subseque
2c030 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
2c040 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
2c050 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b will return.** [
2c060 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e SQLITE_NOMEM].)^
2c070 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a .*/.const void *
2c080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c090 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
2c0a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e *, int iCol);.in
2c0b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
2c0c0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 _bytes(sqlite3_s
2c0d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2c0e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2c0f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 umn_bytes16(sqli
2c100 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
2c110 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c Col);.double sql
2c120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 ite3_column_doub
2c130 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
2c140 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
2c150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c160 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
2c170 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
2c180 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
2c190 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 te3_column_int64
2c1a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2c1b0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 int iCol);.const
2c1c0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
2c1d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2c1e0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ext(sqlite3_stmt
2c1f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f *, int iCol);.co
2c200 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2c210 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2c220 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2c230 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
2c240 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
2c250 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2c260 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 int iCol);.sqli
2c270 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 te3_value *sqlit
2c280 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2c290 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2c2a0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a nt iCol);../*.**
2c2b0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 CAPI3REF: Destr
2c2c0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 oy A Prepared St
2c2d0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
2c2e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2c2f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 3_finalize() fun
2c300 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 ction is called
2c310 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 to delete a [pre
2c320 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2c330 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 ..** ^If the mos
2c340 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 t recent evaluat
2c350 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 ion of the state
2c360 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 ment encountered
2c370 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 no errors.** or
2c380 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e if the statemen
2c390 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 t is never been
2c3a0 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 evaluated, then
2c3b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2c3c0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 () returns.** SQ
2c3d0 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 LITE_OK. ^If th
2c3e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 e most recent ev
2c3f0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 aluation of stat
2c400 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 ement S failed,
2c410 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f then.** sqlite3_
2c420 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 finalize(S) retu
2c430 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 rns the appropri
2c440 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
2c450 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 or.** [extended
2c460 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a error code]..**
2c470 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2c480 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 _finalize(S) rou
2c490 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c tine can be call
2c4a0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 ed at any point
2c4b0 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 during.** the li
2c4c0 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 fe cycle of [pre
2c4d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2c4e0 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 S:.** before st
2c4f0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 atement S is eve
2c500 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 r evaluated, aft
2c510 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 er.** one or mor
2c520 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 e calls to [sqli
2c530 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 te3_reset()], or
2c540 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a after any call.
2c550 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ** to [sqlite3_s
2c560 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 tep()] regardles
2c570 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
2c580 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e not the statemen
2c590 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 t has.** complet
2c5a0 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a ed execution..**
2c5b0 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 .** ^Invoking sq
2c5c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2c5d0 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 on a NULL point
2c5e0 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 er is a harmless
2c5f0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 no-op..**.** Th
2c600 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
2c610 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 st finalize ever
2c620 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 y [prepared stat
2c630 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 ement] in order
2c640 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f to avoid.** reso
2c650 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 urce leaks. It
2c660 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 is a grievous er
2c670 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c ror for the appl
2c680 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 ication to try t
2c690 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 o use.** a prepa
2c6a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 red statement af
2c6b0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
2c6c0 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 finalized. Any
2c6d0 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 use of a prepare
2c6e0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 d.** statement a
2c6f0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e fter it has been
2c700 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 finalized can r
2c710 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e esult in undefin
2c720 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 ed and.** undesi
2c730 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 rable behavior s
2c740 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 uch as segfaults
2c750 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 and heap corrup
2c760 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c tion..*/.int sql
2c770 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 ite3_finalize(sq
2c780 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2c790 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2c7a0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 REF: Reset A Pre
2c7b0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
2c7c0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 Object.**.** The
2c7d0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 sqlite3_reset()
2c7e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c function is cal
2c7f0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b led to reset a [
2c800 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2c810 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 nt].** object ba
2c820 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
2c830 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 l state, ready t
2c840 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 o be re-executed
2c850 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 ..** ^Any SQL st
2c860 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 atement variable
2c870 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 s that had value
2c880 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 s bound to them
2c890 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 using.** the [sq
2c8a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
2c8b0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a | sqlite3_bind_*
2c8c0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 () API] retain t
2c8d0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 heir values..**
2c8e0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 Use [sqlite3_cle
2c8f0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 ar_bindings()] t
2c900 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 o reset the bind
2c910 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ings..**.** ^The
2c920 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2c930 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 S)] interface re
2c940 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 sets the [prepar
2c950 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a ed statement] S.
2c960 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 ** back to the b
2c970 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 eginning of its
2c980 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e program..**.** ^
2c990 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
2c9a0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
2c9b0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
2c9c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
2c9d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 d statement] S r
2c9e0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
2c9f0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f ROW] or [SQLITE_
2ca00 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 DONE],.** or if
2ca10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2ca20 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f ] has never befo
2ca30 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f re been called o
2ca40 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 n S,.** then [sq
2ca50 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
2ca60 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
2ca70 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 OK]..**.** ^If t
2ca80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
2ca90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2caa0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 step(S)] for the
2cab0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
2cac0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 atement] S indic
2cad0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 ated an error, t
2cae0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f hen.** [sqlite3_
2caf0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e reset(S)] return
2cb00 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 s an appropriate
2cb10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a [error code]..*
2cb20 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
2cb30 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 e3_reset(S)] int
2cb40 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 erface does not
2cb50 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
2cb60 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c s.** of any [sql
2cb70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 ite3_bind_blob|b
2cb80 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 indings] on the
2cb90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2cba0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 ent] S..*/.int s
2cbb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c qlite3_reset(sql
2cbc0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2cbd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2cbe0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 EF: Create Or Re
2cbf0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 define SQL Funct
2cc00 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ions.** KEYWORDS
2cc10 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 : {function crea
2cc20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a tion routines}.*
2cc30 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
2cc40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2cc50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a SQL function}.*
2cc60 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
2cc70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2cc80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a SQL functions}.
2cc90 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e **.** ^These fun
2cca0 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 ctions (collecti
2ccb0 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 vely known as "f
2ccc0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
2ccd0 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 routines").** a
2cce0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 re used to add S
2ccf0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
2cd00 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f aggregates or to
2cd10 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 redefine the be
2cd20 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 havior.** of exi
2cd30 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 sting SQL functi
2cd40 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
2cd50 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 s. The only dif
2cd60 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e ferences between
2cd70 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e .** these routin
2cd80 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 es are the text
2cd90 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 encoding expecte
2cda0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 d for.** the sec
2cdb0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 ond parameter (t
2cdc0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 he name of the f
2cdd0 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 unction being cr
2cde0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 eated).** and th
2cdf0 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 e presence or ab
2ce00 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 sence of a destr
2ce10 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 uctor callback f
2ce20 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 or.** the applic
2ce30 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
2ce40 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 er..**.** ^The f
2ce50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
2ce60 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 s the [database
2ce70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 connection] to w
2ce80 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 hich the SQL.**
2ce90 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 function is to b
2cea0 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e e added. ^If an
2ceb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 application use
2cec0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 s more than one
2ced0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
2cee0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c ection then appl
2cef0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2cf00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 SQL functions mu
2cf10 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 st be added.** t
2cf20 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 o each database
2cf30 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 connection separ
2cf40 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ately..**.** ^Th
2cf50 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
2cf60 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
2cf70 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 f the SQL functi
2cf80 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 on to be created
2cf90 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 or.** redefined
2cfa0 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f . ^The length o
2cfb0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 f the name is li
2cfc0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 mited to 255 byt
2cfd0 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a es in a UTF-8.**
2cfe0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c representation,
2cff0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 exclusive of th
2d000 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f e zero-terminato
2d010 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 r. ^Note that t
2d020 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 he name.** lengt
2d030 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 h limit is in UT
2d040 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 F-8 bytes, not c
2d050 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 haracters nor UT
2d060 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a F-16 bytes. .**
2d070 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f ^Any attempt to
2d080 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 create a functi
2d090 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 on with a longer
2d0a0 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 name.** will re
2d0b0 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f sult in [SQLITE_
2d0c0 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 MISUSE] being re
2d0d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
2d0e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
2d0f0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 er (nArg).** is
2d100 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 the number of ar
2d110 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 guments that the
2d120 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
2d130 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 .** aggregate ta
2d140 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 kes. ^If this pa
2d150 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 rameter is -1, t
2d160 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hen the SQL func
2d170 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
2d180 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e gate may take an
2d190 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 y number of argu
2d1a0 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 ments between 0
2d1b0 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a and the limit.**
2d1c0 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 set by [sqlite3
2d1d0 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f _limit]([SQLITE_
2d1e0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
2d1f0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 RG]). If the th
2d200 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ird.** parameter
2d210 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 is less than -1
2d220 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e or greater than
2d230 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 127 then the be
2d240 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 havior is.** und
2d250 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
2d260 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2d270 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 ter, eTextRep, s
2d280 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a pecifies what.**
2d290 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 [SQLITE_UTF8 |
2d2a0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 text encoding] t
2d2b0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e his SQL function
2d2c0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 prefers for.**
2d2d0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 its parameters.
2d2e0 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 Every SQL funct
2d2f0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
2d300 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 on must be able
2d310 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 to work.** with
2d320 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c UTF-8, UTF-16le,
2d330 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 or UTF-16be. B
2d340 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e ut some implemen
2d350 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a tations may be.*
2d360 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 * more efficient
2d370 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 with one encodi
2d380 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e ng than another.
2d390 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f ^An applicatio
2d3a0 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 n may.** invoke
2d3b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2d3c0 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c unction() or sql
2d3d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2d3e0 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c tion16() multipl
2d3f0 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 e.** times with
2d400 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
2d410 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 n but with diffe
2d420 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 rent values of e
2d430 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 TextRep..** ^Whe
2d440 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 n multiple imple
2d450 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
2d460 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
2d470 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 are available, S
2d480 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 QLite.** will pi
2d490 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 ck the one that
2d4a0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 involves the lea
2d4b0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 st amount of dat
2d4c0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a a conversion..**
2d4d0 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c If there is onl
2d4e0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 y a single imple
2d4f0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 mentation which
2d500 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 does not care wh
2d510 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 at text.** encod
2d520 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
2d530 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 n the fourth arg
2d540 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
2d550 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a [SQLITE_ANY]..**
2d560 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 .** ^(The fifth
2d570 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 parameter is an
2d580 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 arbitrary pointe
2d590 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e r. The implemen
2d5a0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a tation of the.**
2d5b0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 function can ga
2d5c0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 in access to thi
2d5d0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 s pointer using
2d5e0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
2d5f0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e ta()].)^.**.** ^
2d600 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e The sixth, seven
2d610 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 th and eighth pa
2d620 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c rameters, xFunc,
2d630 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 xStep and xFina
2d640 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 l, are.** pointe
2d650 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 rs to C-language
2d660 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
2d670 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 implement the SQ
2d680 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a L function or.**
2d690 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 aggregate. ^A s
2d6a0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 calar SQL functi
2d6b0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 on requires an i
2d6c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2d6d0 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 the xFunc.** ca
2d6e0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c llback only; NUL
2d6f0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 L pointers must
2d700 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
2d710 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 xStep and xFina
2d720 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e l.** parameters.
2d730 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 ^An aggregate S
2d740 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 QL function requ
2d750 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e ires an implemen
2d760 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a tation of xStep.
2d770 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e ** and xFinal an
2d780 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d d NULL pointer m
2d790 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f ust be passed fo
2d7a0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c r xFunc. ^To del
2d7b0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a ete an existing.
2d7c0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ** SQL function
2d7d0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 or aggregate, pa
2d7e0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 ss NULL pointers
2d7f0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 for all three f
2d800 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 unction.** callb
2d810 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 acks..**.** ^(If
2d820 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d the ninth param
2d830 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
2d840 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
2d850 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c v2() is not NULL
2d860 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 ,.** then it is
2d870 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 destructor for t
2d880 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
2d890 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a ata pointer. .**
2d8a0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 The destructor
2d8b0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 is invoked when
2d8c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 the function is
2d8d0 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 deleted, either
2d8e0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 by being.** over
2d8f0 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 loaded or when t
2d900 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2d910 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e ection closes.)^
2d920 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 .** ^The destruc
2d930 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f tor is also invo
2d940 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 ked if the call
2d950 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 to.** sqlite3_cr
2d960 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
2d970 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 () fails..** ^Wh
2d980 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f en the destructo
2d990 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 r callback of th
2d9a0 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 e tenth paramete
2d9b0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 r is invoked, it
2d9c0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 .** is passed a
2d9d0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
2d9e0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 which is a copy
2d9f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
2da00 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e on data .** poin
2da10 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 ter which was th
2da20 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 e fifth paramete
2da30 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 r to sqlite3_cre
2da40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
2da50 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 )..**.** ^It is
2da60 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 permitted to reg
2da70 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 ister multiple i
2da80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
2da90 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 f the same.** fu
2daa0 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 nctions with the
2dab0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 same name but w
2dac0 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 ith either diffe
2dad0 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a ring numbers of.
2dae0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 ** arguments or
2daf0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 differing prefer
2db00 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
2db10 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c gs. ^SQLite wil
2db20 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 l use.** the imp
2db30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 lementation that
2db40 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 most closely ma
2db50 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e tches the way in
2db60 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 which the.** SQ
2db70 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 L function is us
2db80 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e ed. ^A function
2db90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2dba0 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 with a non-negat
2dbb0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 ive.** nArg para
2dbc0 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 meter is a bette
2dbd0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 r match than a f
2dbe0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
2dbf0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 tation with.** a
2dc00 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 negative nArg.
2dc10 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 ^A function whe
2dc20 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 re the preferred
2dc30 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a text encoding.*
2dc40 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 * matches the da
2dc50 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 tabase encoding
2dc60 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d is a better.** m
2dc70 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 atch than a func
2dc80 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 tion where the e
2dc90 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 ncoding is diffe
2dca0 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 rent. .** ^A fu
2dcb0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
2dcc0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 encoding differ
2dcd0 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 ence is between
2dce0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 UTF16le and UTF1
2dcf0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 6be.** is a clos
2dd00 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 er match than a
2dd10 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
2dd20 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 he encoding diff
2dd30 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 erence is.** bet
2dd40 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 ween UTF8 and UT
2dd50 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c F16..**.** ^Buil
2dd60 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d t-in functions m
2dd70 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 ay be overloaded
2dd80 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 by new applicat
2dd90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
2dda0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e tions..**.** ^An
2ddb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
2ddc0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 ined function is
2ddd0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 permitted to ca
2dde0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ll other.** SQLi
2ddf0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 te interfaces.
2de00 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 However, such ca
2de10 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 lls must not.**
2de20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
2de30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f se connection no
2de40 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 r finalize or re
2de50 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 set the prepared
2de60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e .** statement in
2de70 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 which the funct
2de80 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
2de90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
2dea0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a reate_function(.
2deb0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
2dec0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 const char *zFu
2ded0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
2dee0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
2def0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
2df00 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
2df10 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
2df20 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
2df30 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
2df40 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
2df50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
2df60 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
2df70 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
2df80 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
2df90 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 text*).);.int sq
2dfa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2dfb0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 ction16(. sqlit
2dfc0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 e3 *db,. const
2dfd0 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e void *zFunctionN
2dfe0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c ame,. int nArg,
2dff0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
2e000 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 . void *pApp,.
2e010 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 void (*xFunc)(s
2e020 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2e030 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
2e040 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
2e050 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f Step)(sqlite3_co
2e060 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
2e070 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
2e080 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 oid (*xFinal)(sq
2e090 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a lite3_context*).
2e0a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
2e0b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
2e0c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
2e0d0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
2e0e0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
2e0f0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
2e100 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
2e110 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
2e120 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
2e130 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
2e140 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
2e150 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
2e160 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2e170 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
2e180 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
2e190 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
2e1a0 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 context*),. voi
2e1b0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 d(*xDestroy)(voi
2e1c0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d*).);../*.** CA
2e1d0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 PI3REF: Text Enc
2e1e0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 odings.**.** The
2e1f0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 se constant defi
2e200 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 ne integer codes
2e210 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 that represent
2e220 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 the various.** t
2e230 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 ext encodings su
2e240 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 pported by SQLit
2e250 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
2e260 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 LITE_UTF8
2e270 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
2e280 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 LITE_UTF16LE
2e290 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
2e2a0 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 LITE_UTF16BE
2e2b0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
2e2c0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 LITE_UTF16
2e2d0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 4 /* Use
2e2e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
2e2f0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
2e300 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 ITE_ANY
2e310 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 5 /* sqlit
2e320 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2e330 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 on only */.#defi
2e340 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f ne SQLITE_UTF16_
2e350 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a ALIGNED 8 /*
2e360 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2e370 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a collation only *
2e380 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
2e390 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 F: Deprecated Fu
2e3a0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 nctions.** DEPRE
2e3b0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 CATED.**.** Thes
2e3c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 e functions are
2e3d0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 [deprecated]. I
2e3e0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 n order to maint
2e3f0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ain.** backwards
2e400 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 compatibility w
2e410 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 ith older code,
2e420 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
2e430 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 continue .** to
2e440 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 be supported. H
2e450 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c owever, new appl
2e460 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
2e470 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 avoid.** the use
2e480 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 of these functi
2e490 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e ons. To help en
2e4a0 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 courage people t
2e4b0 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 o avoid.** using
2e4c0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
2e4d0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 , we are not goi
2e4e0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 ng to tell you w
2e4f0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a hat they do..*/.
2e500 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f #ifndef SQLITE_O
2e510 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 MIT_DEPRECATED.S
2e520 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
2e530 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 int sqlite3_agg
2e540 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c regate_count(sql
2e550 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
2e560 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
2e570 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 D int sqlite3_ex
2e580 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 pired(sqlite3_st
2e590 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 mt*);.SQLITE_DEP
2e5a0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
2e5b0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e te3_transfer_bin
2e5c0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 dings(sqlite3_st
2e5d0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d mt*, sqlite3_stm
2e5e0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 t*);.SQLITE_DEPR
2e5f0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
2e600 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 e3_global_recove
2e610 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f r(void);.SQLITE_
2e620 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 DEPRECATED void
2e630 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 sqlite3_thread_c
2e640 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 leanup(void);.SQ
2e650 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
2e660 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f int sqlite3_memo
2e670 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 ry_alarm(void(*)
2e680 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 (void*,sqlite3_i
2e690 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c nt64,int),void*,
2e6a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
2e6b0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
2e6c0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e PI3REF: Obtainin
2e6d0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 g SQL Function P
2e6e0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a arameter Values.
2e6f0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 **.** The C-lang
2e700 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 uage implementat
2e710 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 ion of SQL funct
2e720 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
2e730 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 tes uses.** this
2e740 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 set of interfac
2e750 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 e routines to ac
2e760 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 cess the paramet
2e770 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 er values on.**
2e780 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 the function or
2e790 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a aggregate..**.**
2e7a0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 The xFunc (for
2e7b0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 scalar functions
2e7c0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 ) or xStep (for
2e7d0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 aggregates) para
2e7e0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 meters.** to [sq
2e7f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2e800 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 ction()] and [sq
2e810 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2e820 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 ction16()].** de
2e830 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 fine callbacks t
2e840 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
2e850 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
2e860 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a and aggregates..
2e870 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d ** The 3rd param
2e880 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 eter to these ca
2e890 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 llbacks is an ar
2e8a0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
2e8b0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 to.** [protected
2e8c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
2e8d0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 objects. There
2e8e0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f is one [sqlite3_
2e8f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f value] object fo
2e900 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 r.** each parame
2e910 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 ter to the SQL f
2e920 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 unction. These
2e930 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
2e940 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 d to.** extract
2e950 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 values from the
2e960 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
2e970 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 objects..**.** T
2e980 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f hese routines wo
2e990 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 rk only with [pr
2e9a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2e9b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
2e9c0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 ** Any attempt t
2e9d0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 o use these rout
2e9e0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 ines on an [unpr
2e9f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2ea00 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 value].** object
2ea10 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 results in unde
2ea20 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
2ea30 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
2ea40 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 tines work just
2ea50 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 like the corresp
2ea60 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 onding [column a
2ea70 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d ccess functions]
2ea80 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
2ea90 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
2eaa0 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 take a single [p
2eab0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2eac0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a _value] object.*
2ead0 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 * pointer instea
2eae0 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f d of a [sqlite3_
2eaf0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 stmt*] pointer a
2eb00 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f nd an integer co
2eb10 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a lumn number..**.
2eb20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2eb30 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 value_text16() i
2eb40 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 nterface extract
2eb50 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e s a UTF-16 strin
2eb60 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 g.** in the nati
2eb70 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 ve byte-order of
2eb80 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e the host machin
2eb90 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 e. ^The.** sqli
2eba0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
2ebb0 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 be() and sqlite3
2ebc0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
2ebd0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
2ebe0 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 extract UTF-16 s
2ebf0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e trings as big-en
2ec00 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d dian and little-
2ec10 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 endian respectiv
2ec20 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ely..**.** ^(The
2ec30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e sqlite3_value_n
2ec40 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e umeric_type() in
2ec50 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
2ec60 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d to apply.** num
2ec70 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f eric affinity to
2ec80 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 the value. Thi
2ec90 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 s means that an
2eca0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 attempt is.** ma
2ecb0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 de to convert th
2ecc0 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e e value to an in
2ecd0 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e teger or floatin
2ece0 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 g point. If.**
2ecf0 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f such a conversio
2ed00 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 n is possible wi
2ed10 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e thout loss of in
2ed20 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 formation (in ot
2ed30 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 her.** words, if
2ed40 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 the value is a
2ed50 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b string that look
2ed60 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 s like a number)
2ed70 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e .** then the con
2ed80 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f version is perfo
2ed90 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 rmed. Otherwise
2eda0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f no conversion o
2edb0 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 ccurs..** The [S
2edc0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 QLITE_INTEGER |
2edd0 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 datatype] after
2ede0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 conversion is re
2edf0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 turned.)^.**.**
2ee00 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 Please pay parti
2ee10 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 cular attention
2ee20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 to the fact that
2ee30 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 the pointer ret
2ee40 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 urned.** from [s
2ee50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
2ee60 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 b()], [sqlite3_v
2ee70 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 alue_text()], or
2ee80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
2ee90 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e ue_text16()] can
2eea0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 be invalidated
2eeb0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 by a subsequent
2eec0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
2eed0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
2eee0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
2eef0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b ue_bytes16()], [
2ef00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2ef10 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
2ef20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2ef30 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 16()]..**.** The
2ef40 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 se routines must
2ef50 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
2ef60 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
2ef70 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 as.** the SQL fu
2ef80 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 nction that supp
2ef90 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 lied the [sqlite
2efa0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 3_value*] parame
2efb0 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 ters..*/.const v
2efc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
2efd0 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f ue_blob(sqlite3_
2efe0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
2eff0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
2f000 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
2f010 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
2f020 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 lue_bytes16(sqli
2f030 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 te3_value*);.dou
2f040 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ble sqlite3_valu
2f050 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 e_double(sqlite3
2f060 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
2f070 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
2f080 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
2f090 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
2f0a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
2f0b0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 64(sqlite3_value
2f0c0 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e *);.const unsign
2f0d0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 ed char *sqlite3
2f0e0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 _value_text(sqli
2f0f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
2f100 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
2f110 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 _value_text16(sq
2f120 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 lite3_value*);.c
2f130 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2f140 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c e3_value_text16l
2f150 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
2f160 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
2f170 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2f180 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 t16be(sqlite3_va
2f190 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
2f1a0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 e3_value_type(sq
2f1b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
2f1c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
2f1d0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 _numeric_type(sq
2f1e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a lite3_value*);..
2f1f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2f200 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 Obtain Aggregate
2f210 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 Function Contex
2f220 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e t.**.** Implemen
2f230 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 tations of aggre
2f240 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
2f250 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 ns use this.** r
2f260 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 outine to alloca
2f270 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 te memory for st
2f280 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 oring their stat
2f290 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 e..**.** ^The fi
2f2a0 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c rst time the sql
2f2b0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
2f2c0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 ontext(C,N) rout
2f2d0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a ine is called .*
2f2e0 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c * for a particul
2f2f0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e ar aggregate fun
2f300 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a ction, SQLite.**
2f310 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 allocates N of
2f320 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f memory, zeroes o
2f330 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 ut that memory,
2f340 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f and returns a po
2f350 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
2f360 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 new memory. ^On
2f370 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 second and subse
2f380 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a quent calls to.*
2f390 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 * sqlite3_aggreg
2f3a0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f ate_context() fo
2f3b0 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 r the same aggre
2f3c0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e gate function in
2f3d0 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 stance,.** the s
2f3e0 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 ame buffer is re
2f3f0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 turned. Sqlite3
2f400 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
2f410 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 xt() is normally
2f420 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 .** called once
2f430 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 for each invocat
2f440 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 ion of the xStep
2f450 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 callback and th
2f460 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 en one.** last t
2f470 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 ime when the xFi
2f480 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 nal callback is
2f490 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e invoked. ^(When
2f4a0 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a no rows match.*
2f4b0 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 * an aggregate q
2f4c0 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 uery, the xStep(
2f4d0 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 ) callback of th
2f4e0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
2f4f0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e tion.** implemen
2f500 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 tation is never
2f510 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 called and xFina
2f520 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 l() is called ex
2f530 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 actly once..** I
2f540 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 n those cases, s
2f550 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
2f560 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 _context() might
2f570 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 be called for t
2f580 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 he.** first time
2f590 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 from within xFi
2f5a0 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e nal().)^.**.** ^
2f5b0 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 The sqlite3_aggr
2f5c0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
2f5d0 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 N) routine retur
2f5e0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
2f5f0 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 r if N is.** les
2f600 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
2f610 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 to zero or if a
2f620 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 memory allocate
2f630 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a error occurs..**
2f640 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 .** ^(The amount
2f650 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 of space alloca
2f660 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 ted by sqlite3_a
2f670 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
2f680 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 (C,N) is.** dete
2f690 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 rmined by the N
2f6a0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 parameter on fir
2f6b0 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 st successful ca
2f6c0 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 ll. Changing th
2f6d0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 e.** value of N
2f6e0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 in subsequent ca
2f6f0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 ll to sqlite3_ag
2f700 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
2f710 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 ) within.** the
2f720 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 same aggregate f
2f730 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 unction instance
2f740 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 will not resize
2f750 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 the memory.** a
2f760 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a llocation.)^.**.
2f770 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d ** ^SQLite autom
2f780 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 atically frees t
2f790 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
2f7a0 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 ted by .** sqlit
2f7b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
2f7c0 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 text() when the
2f7d0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 aggregate query
2f7e0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a concludes..**.**
2f7f0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
2f800 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 eter must be a c
2f810 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 opy of the.** [s
2f820 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c qlite3_context |
2f830 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f SQL function co
2f840 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 ntext] that is t
2f850 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2f860 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 er.** to the xSt
2f870 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c ep or xFinal cal
2f880 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 lback routine th
2f890 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
2f8a0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 e aggregate.** f
2f8b0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 unction..**.** T
2f8c0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
2f8d0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
2f8e0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
2f8f0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
2f900 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
2f910 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
2f920 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 g..*/.void *sqli
2f930 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
2f940 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f ntext(sqlite3_co
2f950 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 ntext*, int nByt
2f960 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 es);../*.** CAPI
2f970 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 3REF: User Data
2f980 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a For Functions.**
2f990 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2f9a0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 _user_data() int
2f9b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2f9c0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
2f9d0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 pointer that was
2f9e0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 the pUserData p
2f9f0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 arameter (the 5t
2fa00 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 h parameter).**
2fa10 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
2fa20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2fa30 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
2fa40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2fa50 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 on16()] routines
2fa60 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 that originally
2fa70 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 .** registered t
2fa80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
2fa90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
2faa0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2fab0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c ine must be call
2fac0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
2fad0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
2fae0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
2faf0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
2fb00 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
2fb10 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
2fb20 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 3_user_data(sqli
2fb30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
2fb40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2fb50 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
2fb60 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e ion For Function
2fb70 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
2fb80 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
2fb90 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 handle() interfa
2fba0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 ce returns a cop
2fbb0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e y of.** the poin
2fbc0 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 ter to the [data
2fbd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2fbe0 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 (the 1st parame
2fbf0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b ter).** of the [
2fc00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2fc10 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e unction()].** an
2fc20 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
2fc30 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 e_function16()]
2fc40 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 routines that or
2fc50 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 iginally.** regi
2fc60 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 stered the appli
2fc70 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 cation defined f
2fc80 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 unction..*/.sqli
2fc90 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e te3 *sqlite3_con
2fca0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 text_db_handle(s
2fcb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
2fcc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2fcd0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 F: Function Auxi
2fce0 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a liary Data.**.**
2fcf0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 The following t
2fd00 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 wo functions may
2fd10 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c be used by scal
2fd20 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ar SQL functions
2fd30 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 to.** associate
2fd40 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 metadata with a
2fd50 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 rgument values.
2fd60 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 If the same valu
2fd70 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a e is passed to.*
2fd80 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 * multiple invoc
2fd90 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
2fda0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 me SQL function
2fdb0 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 during query exe
2fdc0 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a cution, under.**
2fdd0 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e some circumstan
2fde0 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 ces the associat
2fdf0 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 ed metadata may
2fe00 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 be preserved. Th
2fe10 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 is may.** be use
2fe20 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 d, for example,
2fe30 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 to add a regular
2fe40 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 -expression matc
2fe50 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 hing scalar.** f
2fe60 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d unction. The com
2fe70 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 piled version of
2fe80 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 the regular exp
2fe90 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 ression is store
2fea0 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 d as.** metadata
2feb0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
2fec0 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 the SQL value p
2fed0 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 assed as the reg
2fee0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a ular expression.
2fef0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 ** pattern. The
2ff00 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 compiled regula
2ff10 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e r expression can
2ff20 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 be reused on mu
2ff30 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 ltiple.** invoca
2ff40 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2ff50 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 e function so th
2ff60 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 at the original
2ff70 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a pattern string.*
2ff80 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 * does not need
2ff90 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 to be recompiled
2ffa0 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 on each invocat
2ffb0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
2ffc0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
2ffd0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
2ffe0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
2fff0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 r to the metadat
30000 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 a.** associated
30010 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
30020 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e et_auxdata() fun
30030 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e ction with the N
30040 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 th argument.** v
30050 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c alue to the appl
30060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
30070 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f function. ^If no
30080 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 metadata has be
30090 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 en ever.** been
300a0 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 set for the Nth
300b0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 argument of the
300c0 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 function, or if
300d0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
300e0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 g.** function pa
300f0 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e rameter has chan
30100 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 ged since the me
30110 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c ta-data was set,
30120 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 .** then sqlite3
30130 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 _get_auxdata() r
30140 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
30150 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
30160 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
30170 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 xdata() interfac
30180 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 e saves the meta
30190 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 data.** pointed
301a0 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 to by its 3rd pa
301b0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d rameter as the m
301c0 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 etadata for the
301d0 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 N-th.** argument
301e0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
301f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
30200 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e tion. Subsequen
30210 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 t.** calls to sq
30220 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
30230 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e a() might return
30240 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 this data, if i
30250 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 t has.** not bee
30260 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 n destroyed..**
30270 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 ^If it is not NU
30280 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 LL, SQLite will
30290 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
302a0 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f uctor.** functio
302b0 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 n given by the 4
302c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
302d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
302e0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 ata() on.** the
302f0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 metadata when th
30300 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
30310 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 function paramet
30320 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 er changes.** or
30330 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 when the SQL st
30340 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 atement complete
30350 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d s, whichever com
30360 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 es first..**.**
30370 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 SQLite is free t
30380 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 o call the destr
30390 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d uctor and drop m
303a0 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a etadata on any.*
303b0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 * parameter of a
303c0 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 ny function at a
303d0 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f ny time. ^The o
303e0 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 nly guarantee is
303f0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 that.** the des
30400 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 tructor will be
30410 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 called before th
30420 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 e metadata is dr
30430 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 opped..**.** ^(I
30440 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 n practice, meta
30450 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 data is preserve
30460 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 d between functi
30470 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 on calls for.**
30480 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 expressions that
30490 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 are constant at
304a0 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 compile time. T
304b0 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 his includes lit
304c0 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 eral.** values a
304d0 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e nd [parameters].
304e0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 )^.**.** These r
304f0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
30500 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
30510 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
30520 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 hich.** the SQL
30530 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
30540 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ing..*/.void *sq
30550 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
30560 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
30570 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 t*, int N);.void
30580 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
30590 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
305a0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f text*, int N, vo
305b0 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f id*, void (*)(vo
305c0 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 id*));.../*.** C
305d0 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e API3REF: Constan
305e0 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 ts Defining Spec
305f0 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 ial Destructor B
30600 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 ehavior.**.** Th
30610 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 ese are special
30620 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 values for the d
30630 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 estructor that i
30640 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 s passed in as t
30650 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 he.** final argu
30660 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 ment to routines
30670 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 like [sqlite3_r
30680 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 esult_blob()].
30690 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 ^If the destruct
306a0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 or.** argument i
306b0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c s SQLITE_STATIC,
306c0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
306d0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 he content point
306e0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a er is constant.*
306f0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 * and will never
30700 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 change. It doe
30710 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
30720 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 destroyed. ^Th
30730 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e e.** SQLITE_TRAN
30740 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e SIENT value mean
30750 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
30760 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 nt will likely c
30770 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 hange in.** the
30780 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 near future and
30790 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 that SQLite shou
307a0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 ld make its own
307b0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a private copy of.
307c0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 ** the content b
307d0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
307e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 .**.** The typed
307f0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 ef is necessary
30800 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 to work around p
30810 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 roblems in certa
30820 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c in.** C++ compil
30830 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 ers. See ticket
30840 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 #2191..*/.typed
30850 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
30860 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
30870 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 e)(void*);.#defi
30880 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 ne SQLITE_STATIC
30890 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f ((sqlite3_
308a0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
308b0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0).#define SQLIT
308c0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 E_TRANSIENT ((
308d0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
308e0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a or_type)-1)../*.
308f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
30900 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 ting The Result
30910 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 Of An SQL Functi
30920 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 on.**.** These r
30930 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 outines are used
30940 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 by the xFunc or
30950 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
30960 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d s that.** implem
30970 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ent SQL function
30980 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
30990 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 . See.** [sqlit
309a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
309b0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
309c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
309d0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 on16()].** for a
309e0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
309f0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
30a00 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 se functions wor
30a10 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 k very much like
30a20 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 the [parameter
30a30 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 binding] family
30a40 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 of.** functions
30a50 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c used to bind val
30a60 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 ues to host para
30a70 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 meters in prepar
30a80 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a ed statements..*
30a90 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b * Refer to the [
30aa0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 SQL parameter] d
30ab0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
30ac0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
30ad0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e rmation..**.** ^
30ae0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
30af0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 lt_blob() interf
30b00 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
30b10 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 ult from.** an a
30b20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
30b30 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
30b40 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 e the BLOB whose
30b50 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e content is poin
30b60 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 ted.** to by the
30b70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
30b80 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e r and which is N
30b90 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 bytes long wher
30ba0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 e N is the.** th
30bb0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a ird parameter..*
30bc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
30bd0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 3_result_zeroblo
30be0 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 b() interfaces s
30bf0 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 et the result of
30c00 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
30c10 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
30c20 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f tion to be a BLO
30c30 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c B containing all
30c40 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 zero.** bytes a
30c50 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 nd N bytes in si
30c60 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 ze, where N is t
30c70 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
30c80 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2nd parameter..*
30c90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
30ca0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 3_result_double(
30cb0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
30cc0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
30cd0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
30ce0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
30cf0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 ion to be a floa
30d00 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
30d10 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
30d20 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
30d30 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 t..**.** ^The sq
30d40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
30d50 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
30d60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
30d70 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 ) functions.** c
30d80 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ause the impleme
30d90 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f nted SQL functio
30da0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 n to throw an ex
30db0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c ception..** ^SQL
30dc0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 ite uses the str
30dd0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 ing pointed to b
30de0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 y the.** 2nd par
30df0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 ameter of sqlite
30e00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
30e10 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
30e20 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 lt_error16().**
30e30 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 as the text of a
30e40 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e n error message.
30e50 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 ^SQLite interp
30e60 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a rets the error.*
30e70 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 * message string
30e80 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 from sqlite3_re
30e90 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 sult_error() as
30ea0 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a UTF-8. ^SQLite.*
30eb0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 * interprets the
30ec0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
30ed0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
30ee0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 r16() as UTF-16
30ef0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 in native.** byt
30f00 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 e order. ^If th
30f10 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
30f20 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
30f30 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
30f40 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
30f50 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 _error16() is ne
30f60 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
30f70 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 te takes as the
30f80 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
30f90 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 all text up thr
30fa0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
30fb0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
30fc0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 * ^If the third
30fd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
30fe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
30ff0 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 r() or.** sqlite
31000 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
31010 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 () is non-negati
31020 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 ve then SQLite t
31030 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a akes that many.*
31040 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 * bytes (not cha
31050 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 racters) from th
31060 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
31070 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 as the error mes
31080 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 sage..** ^The sq
31090 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
310a0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
310b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
310c0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 ).** routines ma
310d0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 ke a private cop
310e0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d y of the error m
310f0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f essage text befo
31100 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 re.** they retur
31110 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 n. Hence, the c
31120 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
31130 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f can deallocate o
31140 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 r.** modify the
31150 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 text after they
31160 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 return without h
31170 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c arm..** ^The sql
31180 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
31190 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f r_code() functio
311a0 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 n changes the er
311b0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 ror code.** retu
311c0 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 rned by SQLite a
311d0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e s a result of an
311e0 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 error in a func
311f0 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 tion. ^By defau
31200 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 lt,.** the error
31210 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f code is SQLITE_
31220 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 ERROR. ^A subse
31230 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 quent call to sq
31240 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
31250 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 or().** or sqlit
31260 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
31270 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 6() resets the e
31280 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c rror code to SQL
31290 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a ITE_ERROR..**.**
312a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
312b0 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e sult_toobig() in
312c0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 terface causes S
312d0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 QLite to throw a
312e0 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 n error.** indic
312f0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 ating that a str
31300 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 ing or BLOB is t
31310 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 oo long to repre
31320 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 sent..**.** ^The
31330 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
31340 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 nomem() interfac
31350 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
31360 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f to throw an erro
31370 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 r.** indicating
31380 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c that a memory al
31390 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e location failed.
313a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
313b0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 te3_result_int()
313c0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
313d0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
313e0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
313f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
31400 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
31410 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 e 32-bit signed
31420 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
31430 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
31440 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e d argument..** ^
31450 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
31460 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 lt_int64() inter
31470 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
31480 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 turn value.** of
31490 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
314a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
314b0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 n to be the 64-b
314c0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
314d0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e r.** value given
314e0 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 in the 2nd argu
314f0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ment..**.** ^The
31500 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
31510 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 null() interface
31520 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
31530 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
31540 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
31550 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
31560 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
31570 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
31580 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 ult_text(), sqli
31590 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
315a0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6(),.** sqlite3_
315b0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
315c0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 ), and sqlite3_r
315d0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 esult_text16be()
315e0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 interfaces.** s
315f0 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 et the return va
31600 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 lue of the appli
31610 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
31620 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a unction to be.**
31630 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 a text string w
31640 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e hich is represen
31650 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 ted as UTF-8, UT
31660 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
31670 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 order,.** UTF-1
31680 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 6 little endian,
31690 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 or UTF-16 big e
316a0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 ndian, respectiv
316b0 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ely..** ^SQLite
316c0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 takes the text r
316d0 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 esult from the a
316e0 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a pplication from.
316f0 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d ** the 2nd param
31700 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 eter of the sqli
31710 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
31720 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
31730 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 ^If the 3rd para
31740 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
31750 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
31760 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
31770 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
31780 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 n SQLite takes r
31790 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 esult text from
317a0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
317b0 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 r.** through the
317c0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 first zero char
317d0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 acter..** ^If th
317e0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
317f0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
31800 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
31810 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e rfaces.** is non
31820 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 -negative, then
31830 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e as many bytes (n
31840 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f ot characters) o
31850 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f f the text.** po
31860 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 inted to by the
31870 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 2nd parameter ar
31880 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 e taken as the a
31890 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
318a0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 ed.** function r
318b0 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 esult. If the 3
318c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
318d0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
318e0 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 en it.** must be
318f0 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 the byte offset
31900 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 into the string
31910 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 where the NUL t
31920 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a erminator would.
31930 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 ** appear if the
31940 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 string where NU
31950 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 L terminated. I
31960 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 f any NUL charac
31970 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e ters occur.** in
31980 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 the string at a
31990 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 byte offset tha
319a0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 t is less than t
319b0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
319c0 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 3rd.** parameter
319d0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c , then the resul
319e0 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c ting string will
319f0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 contain embedde
31a00 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a d NULs and the.*
31a10 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 * result of expr
31a20 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e essions operatin
31a30 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 g on strings wit
31a40 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 h embedded NULs
31a50 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
31a60 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
31a70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
31a80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
31a90 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
31aa0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
31ab0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e lt_blob is a non
31ac0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 -NULL pointer, t
31ad0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 hen SQLite calls
31ae0 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f that.** functio
31af0 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 n as the destruc
31b00 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 tor on the text
31b10 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 or BLOB result w
31b20 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 hen it has.** fi
31b30 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
31b40 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 t result..** ^If
31b50 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
31b60 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
31b70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
31b80 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a nterfaces or to.
31b90 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
31ba0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 t_blob is the sp
31bb0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 ecial constant S
31bc0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 QLITE_STATIC, th
31bd0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 en SQLite.** ass
31be0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 umes that the te
31bf0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c xt or BLOB resul
31c00 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 t is in constant
31c10 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
31c20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 not.** copy the
31c30 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 content of the p
31c40 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c arameter nor cal
31c50 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f l a destructor o
31c60 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a n the content.**
31c70 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
31c80 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
31c90 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 result..** ^If
31ca0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
31cb0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
31cc0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
31cd0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 terfaces.** or s
31ce0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
31cf0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 ob is the specia
31d00 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 l constant SQLIT
31d10 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 E_TRANSIENT.** t
31d20 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 hen SQLite makes
31d30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 a copy of the r
31d40 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 esult into space
31d50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a obtained from.*
31d60 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
31d70 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 malloc()] before
31d80 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a it returns..**.
31d90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
31da0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 result_value() i
31db0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
31dc0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 e result of.** t
31dd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
31de0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
31df0 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 to be a copy the
31e00 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
31e10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
31e20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 object specified
31e30 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 by the 2nd para
31e40 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 meter. ^The.**
31e50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
31e60 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 alue() interface
31e70 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
31e80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
31e90 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 lue].** so that
31ea0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
31eb0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e ue] specified in
31ec0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d the parameter m
31ed0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 ay change or.**
31ee0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 be deallocated a
31ef0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 fter sqlite3_res
31f00 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 ult_value() retu
31f10 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d rns without harm
31f20 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 ..** ^A [protect
31f30 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
31f40 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 ] object may alw
31f50 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 ays be used wher
31f60 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 e an.** [unprote
31f70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
31f80 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 ue] object is re
31f90 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 quired, so eithe
31fa0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 r.** kind of [sq
31fb0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
31fc0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 ect can be used
31fd0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 with this interf
31fe0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ace..**.** If th
31ff0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
32000 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 called from wit
32010 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e hin the differen
32020 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e t thread.** than
32030 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e the one contain
32040 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 ing the applicat
32050 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
32060 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 tion that receiv
32070 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 ed.** the [sqlit
32080 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e e3_context] poin
32090 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 ter, the results
320a0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
320b0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
320c0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 result_blob(sqli
320d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
320e0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
320f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
32100 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
32110 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 sult_double(sqli
32120 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f te3_context*, do
32130 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 uble);.void sqli
32140 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
32150 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
32160 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 *, const char*,
32170 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
32180 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
32190 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 6(sqlite3_contex
321a0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
321b0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
321c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
321d0 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f _toobig(sqlite3_
321e0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 context*);.void
321f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
32200 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 rror_nomem(sqlit
32210 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f e3_context*);.vo
32220 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
32230 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c t_error_code(sql
32240 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
32250 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
32260 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 3_result_int(sql
32270 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
32280 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
32290 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 3_result_int64(s
322a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
322b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
322c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
322d0 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 sult_null(sqlite
322e0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
322f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
32300 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f _text(sqlite3_co
32310 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
32320 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a ar*, int, void(*
32330 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
32340 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
32350 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f ext16(sqlite3_co
32360 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
32370 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
32380 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
32390 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
323a0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
323b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
323c0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
323d0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
323e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
323f0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 text16be(sqlite3
32400 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
32410 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 void*, int,void
32420 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
32430 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
32440 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 _value(sqlite3_c
32450 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 ontext*, sqlite3
32460 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 _value*);.void s
32470 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
32480 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 roblob(sqlite3_c
32490 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b ontext*, int n);
324a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
324b0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c : Define New Col
324c0 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 lating Sequences
324d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 .**.** ^These fu
324e0 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d nctions add, rem
324f0 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 ove, or modify a
32500 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 [collation] ass
32510 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 ociated.** with
32520 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
32530 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 nnection] specif
32540 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 ied as the first
32550 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
32560 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 ^The name of th
32570 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 e collation is a
32580 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
32590 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
325a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 ate_collation()
325b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 and sqlite3_crea
325c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
325d0 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 ).** and a UTF-1
325e0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
325f0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f ve byte order fo
32600 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
32610 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a _collation16()..
32620 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 ** ^Collation na
32630 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 mes that compare
32640 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 equal according
32650 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 to [sqlite3_str
32660 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 nicmp()] are.**
32670 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 considered to be
32680 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a the same name..
32690 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 **.** ^(The thir
326a0 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 d argument (eTex
326b0 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e tRep) must be on
326c0 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e e of the constan
326d0 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c ts:.** <ul>.** <
326e0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 li> [SQLITE_UTF8
326f0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
32700 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 TE_UTF16LE],.**
32710 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 <li> [SQLITE_UTF
32720 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 16BE],.** <li> [
32730 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f SQLITE_UTF16], o
32740 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 r.** <li> [SQLIT
32750 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
32760 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ..** </ul>)^.**
32770 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 ^The eTextRep ar
32780 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 gument determine
32790 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f s the encoding o
327a0 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 f strings passed
327b0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 .** to the colla
327c0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ting function ca
327d0 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 llback, xCallbac
327e0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 k..** ^The [SQLI
327f0 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 TE_UTF16] and [S
32800 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
32810 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 NED] values for
32820 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 eTextRep.** forc
32830 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 e strings to be
32840 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 UTF16 with nativ
32850 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
32860 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 ^The [SQLITE_UT
32870 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c F16_ALIGNED] val
32880 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 ue for eTextRep
32890 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 forces strings t
328a0 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e o begin.** on an
328b0 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 even byte addre
328c0 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ss..**.** ^The f
328d0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 ourth argument,
328e0 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c pArg, is an appl
328f0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
32900 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 nter that is pas
32910 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 sed.** through a
32920 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
32930 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c ment to the coll
32940 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
32950 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e allback..**.** ^
32960 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 The fifth argume
32970 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 nt, xCallback, i
32980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
32990 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
329a0 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 ction..** ^Multi
329b0 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 ple collating fu
329c0 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 nctions can be r
329d0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 egistered using
329e0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 the same name bu
329f0 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 t.** with differ
32a00 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 ent eTextRep par
32a10 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 ameters and SQLi
32a20 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 te will use whic
32a30 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f hever.** functio
32a40 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c n requires the l
32a50 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 east amount of d
32a60 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 ata transformati
32a70 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 on..** ^If the x
32a80 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e Callback argumen
32a90 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 t is NULL then t
32aa0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
32ab0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 ction is.** dele
32ac0 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 ted. ^When all
32ad0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
32ae0 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 ons having the s
32af0 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c ame name are del
32b00 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f eted,.** that co
32b10 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f llation is no lo
32b20 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a nger usable..**.
32b30 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e ** ^The collatin
32b40 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 g function callb
32b50 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
32b60 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ith a copy of th
32b70 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 e pArg .** appli
32b80 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
32b90 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f ter and with two
32ba0 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 strings in the
32bb0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 encoding specifi
32bc0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 ed.** by the eTe
32bd0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 xtRep argument.
32be0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 The collating f
32bf0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 unction must ret
32c00 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 urn an.** intege
32c10 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 r that is negati
32c20 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 ve, zero, or pos
32c30 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 itive.** if the
32c40 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 first string is
32c50 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c less than, equal
32c60 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 to, or greater
32c70 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c than the second,
32c80 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
32c90 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 . A collating f
32ca0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 unction must alw
32cb0 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 ays return the s
32cc0 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 ame answer.** gi
32cd0 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 ven the same inp
32ce0 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 uts. If two or
32cf0 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 more collating f
32d00 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 unctions are reg
32d10 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 istered.** to th
32d20 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e e same collation
32d30 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 name (using dif
32d40 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 ferent eTextRep
32d50 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c values) then all
32d60 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e .** must give an
32d70 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 equivalent answ
32d80 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 er when invoked
32d90 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 with equivalent
32da0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 strings..** The
32db0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
32dc0 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 on must obey the
32dd0 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 following prope
32de0 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a rties for all.**
32df0 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 strings A, B, a
32e00 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e nd C:.**.** <ol>
32e10 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 .** <li> If A==B
32e20 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c then B==A..** <
32e30 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 li> If A==B and
32e40 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a B==C then A==C..
32e50 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b ** <li> If A<
32e60 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a B THEN B>A..*
32e70 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 * <li> If A<B
32e80 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e and B<C then
32e90 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c A<C..** </ol
32ea0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c >.**.** If a col
32eb0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
32ec0 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 fails any of the
32ed0 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e above constrain
32ee0 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 ts and that.** c
32ef0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
32f00 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 n is registered
32f10 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 and used, then
32f20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
32f30 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 SQLite.** is und
32f40 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
32f50 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 he sqlite3_creat
32f60 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
32f70 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
32f80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
32f90 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 tion().** with t
32fa0 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 he addition that
32fb0 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 the xDestroy ca
32fc0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
32fd0 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a d on pArg when.*
32fe0 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 * the collating
32ff0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 function is dele
33000 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 ted..** ^Collati
33010 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 ng functions are
33020 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 deleted when th
33030 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 ey are overridde
33040 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 n by later.** ca
33050 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 lls to the colla
33060 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 tion creation fu
33070 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 nctions or when
33080 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
33090 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
330a0 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 closed using [sq
330b0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a lite3_close()]..
330c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 **.** ^The xDest
330d0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 roy callback is
330e0 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 <u>not</u> calle
330f0 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c d if the .** sql
33100 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
33110 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 ation_v2() funct
33120 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c ion fails. Appl
33130 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e ications that in
33140 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
33150 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
33160 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e _v2() with a non
33170 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 -NULL xDestroy a
33180 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a rgument should .
33190 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ** check the ret
331a0 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 urn code and dis
331b0 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c pose of the appl
331c0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
331d0 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 nter.** themselv
331e0 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 es rather than e
331f0 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 xpecting SQLite
33200 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 to deal with it
33210 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 for them..** Thi
33220 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 s is different f
33230 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 rom every other
33240 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
33250 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 . The inconsist
33260 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f ency .** is unfo
33270 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e rtunate but cann
33280 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 ot be changed wi
33290 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 thout breaking b
332a0 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d ackwards .** com
332b0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a patibility..**.*
332c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 * See also: [sq
332d0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
332e0 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 needed()] and [s
332f0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
33300 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f _needed16()]..*/
33310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
33320 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 ate_collation(.
33330 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
33340 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
33350 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
33360 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c , . void *pArg,
33370 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
33380 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
33390 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
333a0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 t void*).);.int
333b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
333c0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 ollation_v2(. s
333d0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 qlite3*, . cons
333e0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a t char *zName, .
333f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
33400 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 . void *pArg,.
33410 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 int(*xCompare)(
33420 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
33430 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
33440 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a void*),. void(*
33450 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 xDestroy)(void*)
33460 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
33470 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
33480 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
33490 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
334a0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 Name,. int eTex
334b0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 tRep, . void *p
334c0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d Arg,. int(*xCom
334d0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
334e0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
334f0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
33500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33510 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 Collation Neede
33520 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a d Callbacks.**.*
33530 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 * ^To avoid havi
33540 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 ng to register a
33550 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ll collation seq
33560 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 uences before a
33570 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 database.** can
33580 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c be used, a singl
33590 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
335a0 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 ion may be regis
335b0 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a tered with the.*
335c0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
335d0 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e ection] to be in
335e0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
335f0 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c n undefined coll
33600 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 ation.** sequenc
33610 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a e is required..*
33620 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e *.** ^If the fun
33630 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 ction is registe
33640 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 red using the sq
33650 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
33660 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a needed() API,.**
33670 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 then it is pass
33680 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 ed the names of
33690 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 undefined collat
336a0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 ion sequences as
336b0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f strings.** enco
336c0 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 ded in UTF-8. ^I
336d0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 f sqlite3_collat
336e0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 ion_needed16() i
336f0 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e s used,.** the n
33700 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 ames are passed
33710 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 as UTF-16 in mac
33720 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 hine native byte
33730 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 order..** ^A ca
33740 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e ll to either fun
33750 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 ction replaces t
33760 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c he existing coll
33770 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c ation-needed cal
33780 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 lback..**.** ^(W
33790 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
337a0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 is invoked, the
337b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
337c0 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 passed is a copy
337d0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e .** of the secon
337e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
337f0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
33800 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 needed() or.** s
33810 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
33820 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 _needed16(). Th
33830 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
33840 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 t is the databas
33850 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
33860 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 The third argu
33870 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
33880 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 SQLITE_UTF8], [S
33890 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a QLITE_UTF16BE],.
338a0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 ** or [SQLITE_UT
338b0 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 F16LE], indicati
338c0 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 ng the most desi
338d0 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 rable form of th
338e0 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 e collation.** s
338f0 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e equence function
33900 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 required. The
33910 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
33920 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
33930 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 the.** required
33940 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
33950 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ce.)^.**.** The
33960 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
33970 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 n should registe
33980 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f r the desired co
33990 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a llation using.**
339a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
339b0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b _collation()], [
339c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
339d0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f ollation16()], o
339e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 r.** [sqlite3_cr
339f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
33a00 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 2()]..*/.int sql
33a10 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
33a20 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 eeded(. sqlite3
33a30 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 *, . void*, .
33a40 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
33a50 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 lite3*,int eText
33a60 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 Rep,const char*)
33a70 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
33a80 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
33a90 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
33aa0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 . void*,. void
33ab0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
33ac0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
33ad0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
33ae0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 .#ifdef SQLITE_H
33af0 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 AS_CODEC./*.** S
33b00 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 pecify the key f
33b10 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 or an encrypted
33b20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 database. This
33b30 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 routine should b
33b40 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 e.** called righ
33b50 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f t after sqlite3_
33b60 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 open()..**.** Th
33b70 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d e code to implem
33b80 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 ent this API is
33b90 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e not available in
33ba0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 the public rele
33bb0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ase.** of SQLite
33bc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
33bd0 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 _key(. sqlite3
33be0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
33bf0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
33c00 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 se to be rekeyed
33c10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
33c20 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 *pKey, int nKey
33c30 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 /* The key
33c40 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 */.);../*.** Cha
33c50 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 nge the key on a
33c60 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e n open database.
33c70 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 If the current
33c80 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 database is not
33c90 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 .** encrypted, t
33ca0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c his routine will
33cb0 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 encrypt it. If
33cc0 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 pNew==0 or nNew
33cd0 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 ==0, the.** data
33ce0 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 base is decrypte
33cf0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 d..**.** The cod
33d00 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 e to implement t
33d10 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 his API is not a
33d20 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 vailable in the
33d30 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a public release.*
33d40 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a * of SQLite..*/.
33d50 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 int sqlite3_reke
33d60 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 y(. sqlite3 *db
33d70 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
33d80 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
33d90 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f to be rekeyed */
33da0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 . const void *p
33db0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 Key, int nKey
33dc0 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 /* The new key
33dd0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 */.);../*.** Sp
33de0 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 ecify the activa
33df0 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 tion key for a S
33e00 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e EE database. Un
33e10 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 less .** activat
33e20 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 ed, none of the
33e30 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c SEE routines wil
33e40 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 l work..*/.void
33e50 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 sqlite3_activate
33e60 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 _see(. const ch
33e70 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 ar *zPassPhrase
33e80 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 /* Activa
33e90 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 tion phrase */.)
33ea0 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 ;.#endif..#ifdef
33eb0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 SQLITE_ENABLE_C
33ec0 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 EROD./*.** Speci
33ed0 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f fy the activatio
33ee0 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f n key for a CERO
33ef0 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c D database. Unl
33f00 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 ess .** activate
33f10 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 d, none of the C
33f20 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 EROD routines wi
33f30 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 ll work..*/.void
33f40 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 sqlite3_activat
33f50 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 e_cerod(. const
33f60 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 char *zPassPhra
33f70 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 se /* Act
33f80 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a ivation phrase *
33f90 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a /.);.#endif../*.
33fa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 ** CAPI3REF: Sus
33fb0 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 pend Execution F
33fc0 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a or A Short Time.
33fd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
33fe0 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 3_sleep() functi
33ff0 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 on causes the cu
34000 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 rrent thread to
34010 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f suspend executio
34020 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 n.** for at leas
34030 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 t a number of mi
34040 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 lliseconds speci
34050 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 fied in its para
34060 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 meter..**.** If
34070 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
34080 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 stem does not su
34090 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 pport sleep requ
340a0 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c ests with.** mil
340b0 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 lisecond time re
340c0 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 solution, then t
340d0 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 he time will be
340e0 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a rounded up to.**
340f0 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 the nearest sec
34100 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 ond. The number
34110 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 of milliseconds
34120 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c of sleep actuall
34130 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 y.** requested f
34140 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e rom the operatin
34150 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 g system is retu
34160 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c rned..**.** ^SQL
34170 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 ite implements t
34180 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 his interface by
34190 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c calling the xSl
341a0 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 eep().** method
341b0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b of the default [
341c0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
341d0 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c ect. If the xSl
341e0 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 eep() method.**
341f0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 of the default V
34200 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d FS is not implem
34210 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c ented correctly,
34220 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e or not implemen
34230 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 ted at.** all, t
34240 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
34250 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 of sqlite3_slee
34260 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 p() may deviate
34270 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 from the descrip
34280 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 tion.** in the p
34290 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
342a0 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 hs..*/.int sqlit
342b0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a e3_sleep(int);..
342c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
342d0 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 Name Of The Fold
342e0 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f er Holding Tempo
342f0 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a rary Files.**.**
34300 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 ^(If this globa
34310 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 l variable is ma
34320 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 de to point to a
34330 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
34340 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
34350 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e a folder (a.k.a.
34360 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 directory), the
34370 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 n all temporary
34380 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 files.** created
34390 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 by SQLite when
343a0 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e using a built-in
343b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 [sqlite3_vfs |
343c0 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 VFS].** will be
343d0 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 placed in that d
343e0 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 irectory.)^ ^If
343f0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a this variable.*
34400 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
34410 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ter, then SQLite
34420 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 performs a sear
34430 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 ch for an approp
34440 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 riate.** tempora
34450 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 ry file director
34460 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e y..**.** It is n
34470 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 ot safe to read
34480 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 or modify this v
34490 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 ariable in more
344a0 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 than one.** thre
344b0 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 ad at a time. I
344c0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f t is not safe to
344d0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 read or modify
344e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a this variable.**
344f0 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 if a [database
34500 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 connection] is b
34510 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 eing used at the
34520 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 same time in a
34530 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 separate.** thre
34540 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 ad..** It is int
34550 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 ended that this
34560 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 variable be set
34570 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 once.** as part
34580 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 of process initi
34590 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 alization and be
345a0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 fore any SQLite
345b0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 interface.** rou
345c0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 tines have been
345d0 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 called and that
345e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 this variable re
345f0 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a main unchanged.*
34600 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a * thereafter..**
34610 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 .** ^The [temp_s
34620 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
34630 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 ragma] may modif
34640 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 y this variable
34650 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 and cause.** it
34660 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f to point to memo
34670 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
34680 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
34690 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 ]. ^Furthermore
346a0 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 ,.** the [temp_s
346b0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
346c0 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 ragma] always as
346d0 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 sumes that any s
346e0 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 tring.** that th
346f0 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e is variable poin
34700 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e ts to is held in
34710 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
34720 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 from .** [sqlit
34730 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 e3_malloc] and t
34740 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 he pragma may at
34750 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 tempt to free th
34760 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 at memory.** usi
34770 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ng [sqlite3_free
34780 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 ]..** Hence, if
34790 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 this variable is
347a0 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 modified direct
347b0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 ly, either it sh
347c0 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 ould be.** made
347d0 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 NULL or made to
347e0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 point to memory
347f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
34800 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a qlite3_malloc].*
34810 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 * or else the us
34820 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 e of the [temp_s
34830 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
34840 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 ragma] should be
34850 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c avoided..*/.SQL
34860 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 ITE_EXTERN char
34870 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 *sqlite3_temp_di
34880 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 rectory;../*.**
34890 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 CAPI3REF: Test F
348a0 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d or Auto-Commit M
348b0 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ode.** KEYWORDS:
348c0 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 {autocommit mod
348d0 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 e}.**.** ^The sq
348e0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f lite3_get_autoco
348f0 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 mmit() interface
34900 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
34910 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 o or.** zero if
34920 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 the given databa
34930 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
34940 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 or is not in au
34950 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a tocommit mode,.*
34960 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 * respectively.
34970 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 ^Autocommit mod
34980 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 e is on by defau
34990 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d lt..** ^Autocomm
349a0 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 it mode is disab
349b0 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d led by a [BEGIN]
349c0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e statement..** ^
349d0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
349e0 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 is re-enabled by
349f0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b a [COMMIT] or [
34a00 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a ROLLBACK]..**.**
34a10 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 If certain kind
34a20 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 s of errors occu
34a30 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 r on a statement
34a40 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d within a multi-
34a50 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 statement.** tra
34a60 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 nsaction (errors
34a70 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 including [SQLI
34a80 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 TE_FULL], [SQLIT
34a90 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 E_IOERR],.** [SQ
34aa0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 LITE_NOMEM], [SQ
34ab0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 LITE_BUSY], and
34ac0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
34ad0 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 T]) then the.**
34ae0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 transaction migh
34af0 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b t be rolled back
34b00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
34b10 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f The only way to
34b20 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 .** find out whe
34b30 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f ther SQLite auto
34b40 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
34b50 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 back the transa
34b60 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 ction after.** a
34b70 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 n error is to us
34b80 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e e this function.
34b90 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 .**.** If anothe
34ba0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 r thread changes
34bb0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 the autocommit
34bc0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 status of the da
34bd0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
34be0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 tion while this
34bf0 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 routine is runni
34c00 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 ng, then the ret
34c10 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 urn value.** is
34c20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e undefined..*/.in
34c30 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 t sqlite3_get_au
34c40 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 tocommit(sqlite3
34c50 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
34c60 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 REF: Find The Da
34c70 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 tabase Handle Of
34c80 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
34c90 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ement.**.** ^The
34ca0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 sqlite3_db_hand
34cb0 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 le interface ret
34cc0 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 urns the [databa
34cd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
34ce0 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 andle.** to whic
34cf0 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 h a [prepared st
34d00 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 atement] belongs
34d10 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 . ^The [databas
34d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
34d30 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
34d40 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 ite3_db_handle i
34d50 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 s the same [data
34d60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
34d70 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 .** that was the
34d80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a first argument.
34d90 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 ** to the [sqlit
34da0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
34db0 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 call (or its va
34dc0 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 riants) that was
34dd0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 used to.** crea
34de0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 te the statement
34df0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c in the first pl
34e00 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 ace..*/.sqlite3
34e10 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 *sqlite3_db_hand
34e20 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
34e30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
34e40 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46 EF: Return The F
34e50 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 ilename For A Da
34e60 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
34e70 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c n.**.** ^The sql
34e80 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 ite3_db_filename
34e90 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (D,N) interface
34ea0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
34eb0 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a r to a filename.
34ec0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
34ed0 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66 th database N of
34ee0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 connection D.
34ef0 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 ^The main databa
34f00 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 se file.** has t
34f10 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 he name "main".
34f20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 If there is no
34f30 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
34f40 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62 e N on the datab
34f50 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
34f60 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62 n D, or if datab
34f70 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f ase N is a tempo
34f80 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 rary or in-memor
34f90 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e y database, then
34fa0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
34fb0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
34fc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e **.** ^The filen
34fd0 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 ame returned by
34fe0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 this function is
34ff0 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74 the output of t
35000 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e he.** xFullPathn
35010 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ame method of th
35020 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 e [VFS]. ^In ot
35030 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66 her words, the f
35040 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 ilename.** will
35050 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 be an absolute p
35060 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 athname, even if
35070 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 the filename us
35080 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 ed.** to open th
35090 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69 e database origi
350a0 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20 nally was a URI
350b0 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 or relative path
350c0 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 name..*/.const c
350d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f har *sqlite3_db_
350e0 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 filename(sqlite3
350f0 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 *db, const char
35100 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a *zDbName);../*.
35110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
35120 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74 61 ermine if a data
35130 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c base is read-onl
35140 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c y.**.** ^The sql
35150 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 ite3_db_readonly
35160 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (D,N) interface
35170 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 68 65 returns 1 if the
35180 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f database N.** o
35190 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69 f connection D i
351a0 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 s read-only, 0 i
351b0 66 20 69 74 20 69 73 20 72 65 61 64 2f 77 72 69 f it is read/wri
351c0 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20 69 te, or -1 if N i
351d0 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d s not.** the nam
351e0 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 e of a database
351f0 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e on connection D.
35200 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
35210 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 db_readonly(sqli
35220 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 te3 *db, const c
35230 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a har *zDbName);..
35240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
35250 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 Find the next pr
35260 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
35270 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 .**.** ^This int
35280 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
35290 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
352a0 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 next [prepared s
352b0 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a tatement] after.
352c0 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 ** pStmt associa
352d0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 ted with the [da
352e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
352f0 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 n] pDb. ^If pSt
35300 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 mt is NULL.** th
35310 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 en this interfac
35320 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
35330 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 ter to the first
35340 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
35350 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ent.** associate
35360 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 d with the datab
35370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 ase connection p
35380 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 Db. ^If no prep
35390 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
353a0 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 * satisfies the
353b0 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 conditions of th
353c0 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 is routine, it r
353d0 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a eturns NULL..**.
353e0 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 ** The [database
353f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 connection] poi
35400 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c nter D in a call
35410 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
35420 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 next_stmt(D,S)]
35430 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e must refer to an
35440 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a open database.*
35450 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 * connection and
35460 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d in particular m
35470 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c ust not be a NUL
35480 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 L pointer..*/.sq
35490 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 lite3_stmt *sqli
354a0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 te3_next_stmt(sq
354b0 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 lite3 *pDb, sqli
354c0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
354d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
354e0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f F: Commit And Ro
354f0 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 llback Notificat
35500 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ion Callbacks.**
35510 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
35520 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 _commit_hook() i
35530 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
35540 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a rs a callback.**
35550 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
35560 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
35570 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
35580 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d s [COMMIT | comm
35590 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 itted]..** ^Any
355a0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 callback set by
355b0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 a previous call
355c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 to sqlite3_commi
355d0 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 t_hook().** for
355e0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
355f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
35600 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e overridden..** ^
35610 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c The sqlite3_roll
35620 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 back_hook() inte
35630 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
35640 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 a callback.** fu
35650 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 nction to be inv
35660 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 oked whenever a
35670 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b transaction is [
35680 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 ROLLBACK | rolle
35690 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 d back]..** ^Any
356a0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 callback set by
356b0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c a previous call
356c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c to sqlite3_roll
356d0 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 back_hook().** f
356e0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
356f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
35700 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
35710 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 * ^The pArg argu
35720 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 ment is passed t
35730 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 hrough to the ca
35740 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 llback..** ^If t
35750 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 he callback on a
35760 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e commit hook fun
35770 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f ction returns no
35780 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 n-zero,.** then
35790 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f the commit is co
357a0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 nverted into a r
357b0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e ollback..**.** ^
357c0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d The sqlite3_comm
357d0 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 it_hook(D,C,P) a
357e0 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 nd sqlite3_rollb
357f0 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 ack_hook(D,C,P)
35800 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 functions.** ret
35810 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 urn the P argume
35820 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 nt from the prev
35830 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 ious call of the
35840 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a same function.*
35850 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 * on the same [d
35860 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
35870 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 on] D, or NULL f
35880 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 or.** the first
35890 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 call for each fu
358a0 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a nction on D..**.
358b0 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e ** The commit an
358c0 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 d rollback hook
358d0 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f callbacks are no
358e0 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 t reentrant..**
358f0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 The callback imp
35900 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 lementation must
35910 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
35920 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
35930 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
35940 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
35950 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 t invoked the ca
35960 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 llback. Any act
35970 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 ions.** to modif
35980 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 y the database c
35990 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 onnection must b
359a0 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c e deferred until
359b0 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f after the.** co
359c0 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 mpletion of the
359d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
359e0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
359f0 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a ered the commit.
35a00 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 ** or rollback h
35a10 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 ook in the first
35a20 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 place..** Note
35a30 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 that running any
35a40 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74 65 other SQL state
35a50 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 ments, including
35a60 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e SELECT statemen
35a70 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 ts,.** or merely
35a80 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
35a90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
35aa0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
35ab0 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 p()] will modify
35ac0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
35ad0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
35ae0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
35af0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
35b00 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
35b10 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 * ^Registering a
35b20 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 NULL function d
35b30 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c isables the call
35b40 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 back..**.** ^Whe
35b50 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f n the commit hoo
35b60 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 k callback routi
35b70 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c ne returns zero,
35b80 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a the [COMMIT].**
35b90 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c operation is al
35ba0 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 lowed to continu
35bb0 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 e normally. ^If
35bc0 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b the commit hook
35bd0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d .** returns non-
35be0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b zero, then the [
35bf0 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 COMMIT] is conve
35c00 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c rted into a [ROL
35c10 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 LBACK]..** ^The
35c20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 rollback hook is
35c30 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f invoked on a ro
35c40 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 llback that resu
35c50 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 lts from a commi
35c60 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e t.** hook return
35c70 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 ing non-zero, ju
35c80 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 st as it would b
35c90 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 e with any other
35ca0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a rollback..**.**
35cb0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 ^For the purpos
35cc0 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 es of this API,
35cd0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
35ce0 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 said to have be
35cf0 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 en.** rolled bac
35d00 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 k if an explicit
35d10 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 "ROLLBACK" stat
35d20 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 ement is execute
35d30 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f d, or.** an erro
35d40 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 r or constraint
35d50 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 causes an implic
35d60 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f it rollback to o
35d70 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f ccur..** ^The ro
35d80 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 llback callback
35d90 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 is not invoked i
35da0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 f a transaction
35db0 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 is.** automatica
35dc0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 lly rolled back
35dd0 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 because the data
35de0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
35df0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a is closed..**.**
35e00 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
35e10 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
35e20 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ok()] interface.
35e30 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
35e40 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 3_commit_hook(sq
35e50 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 lite3*, int(*)(v
35e60 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 oid*), void*);.v
35e70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c oid *sqlite3_rol
35e80 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 lback_hook(sqlit
35e90 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 e3*, void(*)(voi
35ea0 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f d *), void*);../
35eb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
35ec0 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 ata Change Notif
35ed0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b ication Callback
35ee0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
35ef0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
35f00 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 () interface reg
35f10 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
35f20 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 k function.** wi
35f30 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
35f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 connection] ide
35f50 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 ntified by the f
35f60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a irst argument.**
35f70 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
35f80 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 henever a row is
35f90 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 updated, insert
35fa0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a ed or deleted..*
35fb0 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 * ^Any callback
35fc0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 set by a previou
35fd0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 s call to this f
35fe0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 unction.** for t
35ff0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
36000 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
36010 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a verridden..**.**
36020 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 ^The second arg
36030 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
36040 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 er to the functi
36050 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 on to invoke whe
36060 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 n a.** row is up
36070 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
36080 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e or deleted..** ^
36090 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
360a0 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 nt to the callba
360b0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ck is a copy of
360c0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
360d0 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 nt.** to sqlite3
360e0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a _update_hook()..
360f0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 ** ^The second c
36100 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 allback argument
36110 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 is one of [SQLI
36120 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c TE_INSERT], [SQL
36130 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 ITE_DELETE],.**
36140 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 or [SQLITE_UPDAT
36150 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e E], depending on
36160 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 the operation t
36170 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 hat caused the c
36180 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 allback.** to be
36190 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 invoked..** ^Th
361a0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 e third and four
361b0 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 th arguments to
361c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e the callback con
361d0 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f tain pointers to
361e0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
361f0 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 and table name
36200 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 containing the a
36210 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 ffected row..**
36220 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 ^The final callb
36230 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 ack parameter is
36240 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
36250 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 the row..** ^In
36260 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 the case of an u
36270 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 pdate, this is t
36280 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 he [rowid] after
36290 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 the update take
362a0 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e s place..**.** ^
362b0 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b (The update hook
362c0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 is not invoked
362d0 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 when internal sy
362e0 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a stem tables are.
362f0 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 ** modified (i.e
36300 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 . sqlite_master
36310 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 and sqlite_seque
36320 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 nce).)^.**.** ^I
36330 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d n the current im
36340 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 plementation, th
36350 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a e update hook.**
36360 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 is not invoked
36370 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e when duplication
36380 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 rows are delete
36390 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a d because of an.
363a0 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 ** [ON CONFLICT
363b0 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 | ON CONFLICT RE
363c0 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 PLACE] clause.
363d0 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 ^Nor is the upda
363e0 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b te hook.** invok
363f0 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 ed when rows are
36400 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 deleted using t
36410 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 he [truncate opt
36420 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 imization]..** T
36430 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 he exceptions de
36440 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 fined in this pa
36450 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 ragraph might ch
36460 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 ange in a future
36470 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 .** release of S
36480 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 QLite..**.** The
36490 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 update hook imp
364a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 lementation must
364b0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
364c0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
364d0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
364e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
364f0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 t invoked the up
36500 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 date hook. Any
36510 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f actions.** to mo
36520 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 dify the databas
36530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 e connection mus
36540 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e t be deferred un
36550 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a til after the.**
36560 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 completion of t
36570 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
36580 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ()] call that tr
36590 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 iggered the upda
365a0 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 te hook..** Note
365b0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
365c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
365d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
365e0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
365f0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
36600 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
36610 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
36620 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
36630 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
36640 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 ^The sqlite3_up
36650 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 date_hook(D,C,P)
36660 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 function.** ret
36670 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d urns the P argum
36680 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 ent from the pre
36690 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e vious call.** on
366a0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
366b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
366c0 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a D, or NULL for.*
366d0 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c * the first call
366e0 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 on D..**.** See
366f0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 also the [sqlit
36700 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 e3_commit_hook()
36710 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c ], [sqlite3_roll
36720 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 2c 0a 2a 2a back_hook()],.**
36730 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
36740 65 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 eupdate_hook()]
36750 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 interfaces..*/.v
36760 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 oid *sqlite3_upd
36770 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 ate_hook(. sqli
36780 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 te3*, . void(*)
36790 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 (void *,int ,cha
367a0 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 r const *,char c
367b0 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 onst *,sqlite3_i
367c0 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 nt64),. void*.)
367d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
367e0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 F: Enable Or Dis
367f0 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 able Shared Page
36800 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f r Cache.** KEYWO
36810 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 RDS: {shared cac
36820 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 he}.**.** ^(This
36830 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 routine enables
36840 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
36850 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 sharing of the
36860 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a database cache.*
36870 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 * and schema dat
36880 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 a structures bet
36890 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 ween [database c
368a0 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e onnection | conn
368b0 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 ections].** to t
368c0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
368d0 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 . Sharing is ena
368e0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 bled if the argu
368f0 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 ment is true.**
36900 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 and disabled if
36910 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 the argument is
36920 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e false.)^.**.** ^
36930 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 Cache sharing is
36940 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 enabled and dis
36950 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 abled for an ent
36960 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 ire process..**
36970 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 This is a change
36980 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 as of SQLite ve
36990 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 rsion 3.5.0. In
369a0 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f prior versions o
369b0 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 f SQLite,.** sha
369c0 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 ring was enabled
369d0 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 or disabled for
369e0 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 each thread sep
369f0 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e arately..**.** ^
36a00 28 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69 (The cache shari
36a10 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 ng mode set by t
36a20 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 his interface ef
36a30 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 fects all subseq
36a40 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f uent.** calls to
36a50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
36a60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
36a70 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c _v2()], and [sql
36a80 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a ite3_open16()]..
36a90 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 ** Existing data
36aa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
36ab0 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 continue use th
36ac0 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a e sharing mode.*
36ad0 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 * that was in ef
36ae0 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 fect at the time
36af0 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 they were opene
36b00 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 d.)^.**.** ^(Thi
36b10 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
36b20 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 s [SQLITE_OK] if
36b30 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 shared cache wa
36b40 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 s enabled or dis
36b50 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 abled.** success
36b60 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f fully. An [erro
36b70 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
36b80 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e ned otherwise.)^
36b90 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 .**.** ^Shared c
36ba0 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 ache is disabled
36bb0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 by default. But
36bc0 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e this might chan
36bd0 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 ge in.** future
36be0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
36bf0 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e te. Application
36c00 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 s that care abou
36c10 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 t shared.** cach
36c20 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 e setting should
36c30 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 set it explicit
36c40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c ly..**.** See Al
36c50 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 so: [SQLite Sha
36c60 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a red-Cache Mode].
36c70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 */.int sqlite3_e
36c80 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 nable_shared_cac
36c90 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 he(int);../*.**
36ca0 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 CAPI3REF: Attemp
36cb0 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d t To Free Heap M
36cc0 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 emory.**.** ^The
36cd0 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 sqlite3_release
36ce0 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 _memory() interf
36cf0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
36d00 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 free N bytes.**
36d10 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 of heap memory b
36d20 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e y deallocating n
36d30 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d on-essential mem
36d40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a ory allocations.
36d50 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 ** held by the d
36d60 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e atabase library.
36d70 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 Memory used t
36d80 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 o cache database
36d90 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 .** pages to imp
36da0 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 rove performance
36db0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f is an example o
36dc0 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 f non-essential
36dd0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 memory..** ^sqli
36de0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
36df0 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 ry() returns the
36e00 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
36e10 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c actually freed,
36e20 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 .** which might
36e30 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 be more or less
36e40 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 than the amount
36e50 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 requested..** ^T
36e60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 he sqlite3_relea
36e70 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 se_memory() rout
36e80 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 ine is a no-op r
36e90 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a eturning zero.**
36ea0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f if SQLite is no
36eb0 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 t compiled with
36ec0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
36ed0 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 EMORY_MANAGEMENT
36ee0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
36ef0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 72 o: [sqlite3_db_r
36f00 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d elease_memory()]
36f10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
36f20 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 release_memory(i
36f30 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
36f40 33 52 45 46 3a 20 46 72 65 65 20 4d 65 6d 6f 72 3REF: Free Memor
36f50 79 20 55 73 65 64 20 42 79 20 41 20 44 61 74 61 y Used By A Data
36f60 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
36f70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
36f80 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 e3_db_release_me
36f90 6d 6f 72 79 28 44 29 20 69 6e 74 65 72 66 61 63 mory(D) interfac
36fa0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 e attempts to fr
36fb0 65 65 20 61 73 20 6d 75 63 68 20 68 65 61 70 0a ee as much heap.
36fc0 2a 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70 6f 73 ** memory as pos
36fd0 73 69 62 6c 65 20 66 72 6f 6d 20 64 61 74 61 62 sible from datab
36fe0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 ase connection D
36ff0 2e 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 . Unlike the.**
37000 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 [sqlite3_release
37010 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74 65 72 _memory()] inter
37020 66 61 63 65 2c 20 74 68 69 73 20 69 6e 74 65 72 face, this inter
37030 66 61 63 65 20 69 73 20 65 66 66 65 63 74 20 65 face is effect e
37040 76 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 6e ven.** when then
37050 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
37060 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e MEMORY_MANAGEMEN
37070 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 T] compile-time
37080 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69 option is.** omi
37090 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 tted..**.** See
370a0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 also: [sqlite3_r
370b0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d elease_memory()]
370c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
370d0 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 db_release_memor
370e0 79 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a y(sqlite3*);../*
370f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d .** CAPI3REF: Im
37100 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 pose A Limit On
37110 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 Heap Size.**.**
37120 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 ^The sqlite3_sof
37130 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 t_heap_limit64()
37140 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
37150 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74 and/or queries t
37160 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 he.** soft limit
37170 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f on the amount o
37180 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 f heap memory th
37190 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 at may be alloca
371a0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a ted by SQLite..*
371b0 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76 65 * ^SQLite strive
371c0 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20 6d s to keep heap m
371d0 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 6f emory utilizatio
371e0 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 n below the soft
371f0 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 heap.** limit b
37200 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 6e y reducing the n
37210 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 68 umber of pages h
37220 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65 20 eld in the page
37230 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 cache.** as heap
37240 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20 61 memory usages a
37250 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c 69 pproaches the li
37260 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 mit..** ^The sof
37270 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 t heap limit is
37280 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 65 "soft" because e
37290 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 74 ven though SQLit
372a0 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74 61 e strives to sta
372b0 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c y.** below the l
372c0 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 imit, it will ex
372d0 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20 72 ceed the limit r
372e0 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65 72 ather than gener
372f0 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 ate.** an [SQLIT
37300 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 E_NOMEM] error.
37310 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
37320 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
37330 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 imit .** is advi
37340 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a sory only..**.**
37350 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c ^The return val
37360 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
37370 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 soft_heap_limit6
37380 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65 20 4() is the size
37390 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 of.** the soft h
373a0 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 eap limit prior
373b0 74 6f 20 74 68 65 20 63 61 6c 6c 2c 20 6f 72 20 to the call, or
373c0 6e 65 67 61 74 69 76 65 20 69 6e 20 74 68 65 20 negative in the
373d0 63 61 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 65 72 case of an.** er
373e0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 72 ror. ^If the ar
373f0 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 gument N is nega
37400 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 tive.** then no
37410 63 68 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74 change is made t
37420 6f 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 o the soft heap
37430 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 limit. Hence, t
37440 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 he current.** si
37450 7a 65 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68 ze of the soft h
37460 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 eap limit can be
37470 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69 determined by i
37480 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 nvoking.** sqlit
37490 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
374a0 69 74 36 34 28 29 20 77 69 74 68 20 61 20 6e 65 it64() with a ne
374b0 67 61 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e gative argument.
374c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 .**.** ^If the a
374d0 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 rgument N is zer
374e0 6f 20 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20 o then the soft
374f0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69 heap limit is di
37500 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 sabled..**.** ^(
37510 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 The soft heap li
37520 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 mit is not enfor
37530 63 65 64 20 69 6e 20 74 68 65 20 63 75 72 72 65 ced in the curre
37540 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f nt implementatio
37550 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d n.** if one or m
37560 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 ore of following
37570 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 conditions are
37580 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e true:.**.** <ul>
37590 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 .** <li> The sof
375a0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 t heap limit is
375b0 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 set to zero..**
375c0 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f <li> Memory acco
375d0 75 6e 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c unting is disabl
375e0 65 64 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 ed using a combi
375f0 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a nation of the.**
37600 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
37610 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
37620 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
37630 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 ,...) start-time
37640 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 option and.**
37650 20 20 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f the [SQLITE_
37660 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 DEFAULT_MEMSTATU
37670 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 S] compile-time
37680 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 option..** <li>
37690 41 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 An alternative p
376a0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d age cache implem
376b0 65 6e 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63 entation is spec
376c0 69 66 69 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 ified using.**
376d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e [sqlite3_con
376e0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
376f0 46 49 47 5f 50 43 41 43 48 45 32 5d 2c 2e 2e 2e FIG_PCACHE2],...
37700 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 )..** <li> The p
37710 61 67 65 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 age cache alloca
37720 74 65 73 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e tes from its own
37730 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 memory pool sup
37740 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 plied.** by
37750 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
37760 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
37770 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 _PAGECACHE],...)
37780 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 rather than.**
37790 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 68 65 from the he
377a0 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a ap..** </ul>)^.*
377b0 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 *.** Beginning w
377c0 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 ith SQLite versi
377d0 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f on 3.7.3, the so
377e0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 ft heap limit is
377f0 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 enforced.** reg
37800 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
37810 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 er or not the [S
37820 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
37830 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a ORY_MANAGEMENT].
37840 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
37850 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 option is invoke
37860 64 2e 20 20 57 69 74 68 20 5b 53 51 4c 49 54 45 d. With [SQLITE
37870 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d _ENABLE_MEMORY_M
37880 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 ANAGEMENT],.** t
37890 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
378a0 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 20 6f it is enforced o
378b0 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 n every memory a
378c0 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 llocation. With
378d0 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 out.** [SQLITE_E
378e0 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e NABLE_MEMORY_MAN
378f0 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f AGEMENT], the so
37900 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 ft heap limit is
37910 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a only enforced.*
37920 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 * when memory is
37930 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 allocated by th
37940 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 e page cache. T
37950 65 73 74 69 6e 67 20 73 75 67 67 65 73 74 73 20 esting suggests
37960 74 68 61 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 that because.**
37970 74 68 65 20 70 61 67 65 20 63 61 63 68 65 20 69 the page cache i
37980 73 20 74 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 s the predominat
37990 65 20 6d 65 6d 6f 72 79 20 75 73 65 72 20 69 6e e memory user in
379a0 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a SQLite, most.**
379b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 applications wi
379c0 6c 6c 20 61 63 68 69 65 76 65 20 61 64 65 71 75 ll achieve adequ
379d0 61 74 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 ate soft heap li
379e0 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 mit enforcement
379f0 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 without.** the u
37a00 73 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e se of [SQLITE_EN
37a10 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 ABLE_MEMORY_MANA
37a20 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 GEMENT]..**.** T
37a30 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 he circumstances
37a40 20 75 6e 64 65 72 20 77 68 69 63 68 20 53 51 4c under which SQL
37a50 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 ite will enforce
37a60 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
37a70 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e imit may.** chan
37a80 67 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 ges in future re
37a90 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
37aa0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ..*/.sqlite3_int
37ab0 36 34 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 64 sqlite3_soft_
37ac0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 73 71 6c heap_limit64(sql
37ad0 69 74 65 33 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a ite3_int64 N);..
37ae0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
37af0 44 65 70 72 65 63 61 74 65 64 20 53 6f 66 74 20 Deprecated Soft
37b00 48 65 61 70 20 4c 69 6d 69 74 20 49 6e 74 65 72 Heap Limit Inter
37b10 66 61 63 65 0a 2a 2a 20 44 45 50 52 45 43 41 54 face.** DEPRECAT
37b20 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 ED.**.** This is
37b30 20 61 20 64 65 70 72 65 63 61 74 65 64 20 76 65 a deprecated ve
37b40 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 rsion of the [sq
37b50 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
37b60 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 69 6e limit64()].** in
37b70 74 65 72 66 61 63 65 2e 20 20 54 68 69 73 20 72 terface. This r
37b80 6f 75 74 69 6e 65 20 69 73 20 70 72 6f 76 69 64 outine is provid
37b90 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 ed for historica
37ba0 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a l compatibility.
37bb0 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 ** only. All ne
37bc0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 w applications s
37bd0 68 6f 75 6c 64 20 75 73 65 20 74 68 65 0a 2a 2a hould use the.**
37be0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 [sqlite3_soft_h
37bf0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 20 69 eap_limit64()] i
37c00 6e 74 65 72 66 61 63 65 20 72 61 74 68 65 72 20 nterface rather
37c10 74 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e 0a 2a than this one..*
37c20 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 /.SQLITE_DEPRECA
37c30 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 TED void sqlite3
37c40 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
37c50 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a (int N);.../*.**
37c60 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 CAPI3REF: Extra
37c70 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 ct Metadata Abou
37c80 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 t A Column Of A
37c90 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 Table.**.** ^Thi
37ca0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
37cb0 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 s metadata about
37cc0 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 a specific colu
37cd0 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 mn of a specific
37ce0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 .** database tab
37cf0 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 le accessible us
37d00 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 ing the [databas
37d10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
37d20 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 ndle.** passed a
37d30 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 s the first func
37d40 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a tion argument..*
37d50 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e *.** ^The column
37d60 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 is identified b
37d70 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 y the second, th
37d80 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 ird and fourth p
37d90 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 arameters to.**
37da0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e this function. ^
37db0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
37dc0 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 eter is either t
37dd0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
37de0 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e atabase.** (i.e.
37df0 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c "main", "temp",
37e00 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 or an attached
37e10 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 database) contai
37e20 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 ning the specifi
37e30 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e ed.** table or N
37e40 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e ULL. ^If it is N
37e50 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 ULL, then all at
37e60 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
37e70 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a are searched.**
37e80 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 for the table u
37e90 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c sing the same al
37ea0 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 gorithm used by
37eb0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 the database eng
37ec0 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 ine to.** resolv
37ed0 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 e unqualified ta
37ee0 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a ble references..
37ef0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 **.** ^The third
37f00 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 and fourth para
37f10 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 meters to this f
37f20 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 unction are the
37f30 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e table and column
37f40 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 .** name of the
37f50 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 desired column,
37f60 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 respectively. Ne
37f70 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 ither of these p
37f80 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 arameters.** may
37f90 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
37fa0 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74 ^Metadata is ret
37fb0 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 urned by writing
37fc0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c to the memory l
37fd0 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 ocations passed
37fe0 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e as the 5th.** an
37ff0 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 d subsequent par
38000 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 ameters to this
38010 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f function. ^Any o
38020 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 f these argument
38030 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c s may be.** NULL
38040 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 , in which case
38050 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
38060 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 g element of met
38070 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 adata is omitted
38080 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b ..**.** ^(<block
38090 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 quote>.** <table
380a0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 border="1">.**
380b0 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 <tr><th> Paramet
380c0 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 er <th> Output<b
380d0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 r>Type <th> Des
380e0 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c cription.**.** <
380f0 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e tr><td> 5th <td>
38100 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 const char* <td
38110 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c > Data type.** <
38120 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e tr><td> 6th <td>
38130 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 const char* <td
38140 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c > Name of defaul
38150 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 t collation sequ
38160 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ence.** <tr><td>
38170 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 7th <td> int
38180 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 <td> True
38190 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 if column has a
381a0 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 NOT NULL constra
381b0 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 int.** <tr><td>
381c0 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 8th <td> int
381d0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 <td> True i
381e0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 f column is part
381f0 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 of the PRIMARY
38200 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 KEY.** <tr><td>
38210 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 9th <td> int
38220 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 <td> True i
38230 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 f column is [AUT
38240 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c OINCREMENT].** <
38250 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f /table>.** </blo
38260 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
38270 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 ^The memory poi
38280 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 nted to by the c
38290 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 haracter pointer
382a0 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 s returned for t
382b0 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f he.** declaratio
382c0 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 n type and colla
382d0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 tion sequence is
382e0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 valid only unti
382f0 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 l the next.** ca
38300 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 ll to any SQLite
38310 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a API function..*
38320 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 *.** ^If the spe
38330 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 cified table is
38340 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c actually a view,
38350 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
38360 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
38370 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 .** ^If the spec
38380 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 ified column is
38390 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f "rowid", "oid" o
383a0 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 r "_rowid_" and
383b0 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 an.** [INTEGER P
383c0 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 RIMARY KEY] colu
383d0 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c mn has been expl
383e0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c icitly declared,
383f0 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 then the output
38400 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 .** parameters a
38410 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 re set for the e
38420 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
38430 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 ed column. ^(If
38440 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 there is no.** e
38450 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
38460 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d ed [INTEGER PRIM
38470 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c ARY KEY] column,
38480 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 then the output
38490 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 .** parameters a
384a0 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 re set as follow
384b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a s:.**.** <pre>.*
384c0 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a * data type:
384d0 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 "INTEGER".**
384e0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 collation sequ
384f0 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a ence: "BINARY".*
38500 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 * not null:
38510 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 0.** primary
38520 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 key: 1.** a
38530 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 uto increment: 0
38540 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a .** </pre>)^.**.
38550 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 ** ^(This functi
38560 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 on may load one
38570 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 or more schemas
38580 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 from database fi
38590 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 les. If an.** er
385a0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e ror occurs durin
385b0 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 g this process,
385c0 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73 or if the reques
385d0 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c ted table or col
385e0 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 umn.** cannot be
385f0 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f found, an [erro
38600 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
38610 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 ned and an error
38620 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a message left.**
38630 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 in the [databas
38640 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 e connection] (t
38650 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 o be retrieved u
38660 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 sing sqlite3_err
38670 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 msg()).)^.**.**
38680 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c ^This API is onl
38690 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 y available if t
386a0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 he library was c
386b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
386c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
386d0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 LE_COLUMN_METADA
386e0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 TA] C-preprocess
386f0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 or symbol define
38700 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
38710 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 3_table_column_m
38720 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 etadata(. sqlit
38730 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
38740 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 /* Connec
38750 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 tion handle */.
38760 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
38770 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 Name, /*
38780 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 Database name or
38790 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 NULL */. const
387a0 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d char *zTableNam
387b0 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 e, /* Table
387c0 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 name */. const
387d0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d char *zColumnNam
387e0 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 e, /* Column
387f0 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 name */. char c
38800 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 onst **pzDataTyp
38810 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a e, /* OUTPUT:
38820 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 Declared data t
3