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 61 6e 3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 estructors. The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 r.** interfaces
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 ite3_uint64 are
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 int64 types are
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 inclusive. ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 int64 types can
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 YPE. typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 sqlite_int64;.
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 _). typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e se. typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 # define double
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 3REF: Closing A
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
2ac0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
2ad0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 K] if.** the [sq
2ae0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 lite3] object is
2af0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 successfully de
2b00: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 stroyed and all
2b10: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 associated.** re
2b20: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c sources are deal
2b30: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e located..**.** ^
2b40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
2b50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 connection is as
2b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e sociated with un
2b70: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 finalized prepar
2b80: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 ed.** statements
2b90: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 or unfinished s
2ba0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 qlite3_backup ob
2bb0: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 jects then sqlit
2bc0: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 e3_close().** wi
2bd0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 ll leave the dat
2be0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2bf0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e open and return
2c00: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a [SQLITE_BUSY]..
2c10: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 ** ^If sqlite3_c
2c20: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c lose_v2() is cal
2c30: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c led with unfinal
2c40: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 ized prepared st
2c50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f atements.** and/
2c60: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 or unfinished sq
2c70: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 lite3_backups, t
2c80: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
2c90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f connection beco
2ca0: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 mes.** an unusab
2cb0: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 le "zombie" whic
2cc0: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 h will automatic
2cd0: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 ally be dealloca
2ce0: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 ted when the.**
2cf0: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74 last prepared st
2d00: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c atement is final
2d10: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 ized or the last
2d20: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 sqlite3_backup
2d30: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 is.** finished.
2d40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f The sqlite3_clo
2d50: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 se_v2() interfac
2d60: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f e is intended fo
2d70: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f r use with.** ho
2d80: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 st languages tha
2d90: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f t are garbage co
2da0: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 llected, and whe
2db0: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 re the order in
2dc0: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 which.** destruc
2dd0: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 tors are called
2de0: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a is arbitrary..**
2df0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
2e00: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 should [sqlite3
2e10: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 _finalize | fina
2e20: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 lize] all [prepa
2e30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c red statements],
2e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
2e50: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d b_close | close]
2e60: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c all [BLOB handl
2e70: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 es], and .** [sq
2e80: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
2e90: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c ish | finish] al
2ea0: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 l [sqlite3_backu
2eb0: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 p] objects assoc
2ec0: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 iated.** with th
2ed0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
2ee0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 ct prior to atte
2ef0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 mpting to close
2f00: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 the object. ^If
2f10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 .** sqlite3_clos
2f20: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 e_v2() is called
2f30: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 on a [database
2f40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
2f50: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 still has.** ou
2f60: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 tstanding [prepa
2f70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c red statements],
2f80: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c [BLOB handles],
2f90: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 and/or.** [sqli
2fa0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 te3_backup] obje
2fb0: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 cts then it retu
2fc0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
2fd0: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 and the dealloca
2fe0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 tion.** of resou
2ff0: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64 rces is deferred
3000: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 until all [prep
3010: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
3020: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d , [BLOB handles]
3030: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ,.** and [sqlite
3040: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 3_backup] object
3050: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 s are also destr
3060: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 oyed..**.** ^If
3070: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a an [sqlite3] obj
3080: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 ect is destroyed
3090: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 while a transac
30a0: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a tion is open,.**
30b0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
30c0: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c is automaticall
30d0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a y rolled back..*
30e0: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d *.** The C param
30f0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
3100: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b _close(C)] and [
3110: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
3120: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 (C)].** must be
3130: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a either a NULL.**
3140: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b pointer or an [
3150: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
3160: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 pointer obtained
3170: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
3180: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
3190: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f te3_open16()], o
31a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r.** [sqlite3_op
31b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f en_v2()], and no
31c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f t previously clo
31d0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 sed..** ^Calling
31e0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
31f0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 or sqlite3_clos
3200: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 e_v2() with a NU
3210: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 LL pointer.** ar
3220: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d gument is a harm
3230: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 less no-op..*/.i
3240: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nt sqlite3_close
3250: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 (sqlite3*);.int
3260: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
3270: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
3280: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 ** The type for
3290: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
32a0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ion..** This is
32b0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 legacy and depre
32c0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e cated. It is in
32d0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f cluded for histo
32e0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 rical.** compati
32f0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f bility and is no
3300: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f t documented..*/
3310: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 .typedef int (*s
3320: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 qlite3_callback)
3330: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
3340: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a *, char**);../*.
3350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 ** CAPI3REF: One
3360: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 -Step Query Exec
3370: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a ution Interface.
3380: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
3390: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
33a0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 ce is a convenie
33b0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 nce wrapper arou
33c0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 nd.** [sqlite3_p
33d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
33e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
33f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e and [sqlite3_fin
3400: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 alize()],.** tha
3410: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c t allows an appl
3420: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d ication to run m
3430: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e ultiple statemen
3440: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 ts of SQL.** wit
3450: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 hout having to u
3460: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f se a lot of C co
3470: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de. .**.** ^The
3480: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
3490: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 nterface runs ze
34a0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 ro or more UTF-8
34b0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d encoded,.** sem
34c0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 icolon-separate
34d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 SQL statements p
34e0: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 assed into its 2
34f0: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 nd argument,.**
3500: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f in the context o
3510: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
3520: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 connection] pass
3530: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 ed in as its 1st
3540: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e .** argument. ^
3550: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
3560: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 function of the
3570: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 3rd argument to.
3580: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
3590: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 ) is not NULL, t
35a0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 hen it is invoke
35b0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c d for each resul
35c0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 t row.** coming
35d0: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 out of the evalu
35e0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 ated SQL stateme
35f0: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 nts. ^The 4th a
3600: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 rgument to.** sq
3610: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
3620: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 relayed through
3630: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d to the 1st argum
3640: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 ent of each.** c
3650: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 allback invocati
3660: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c on. ^If the cal
3670: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f lback pointer to
3680: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
3690: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e ** is NULL, then
36a0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 no callback is
36b0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 ever invoked and
36c0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 result rows are
36d0: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a .** ignored..**.
36e0: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 ** ^If an error
36f0: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 occurs while eva
3700: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 luating the SQL
3710: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 statements passe
3720: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 d into.** sqlite
3730: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 3_exec(), then e
3740: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
3750: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e current statemen
3760: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 t stops and.** s
3770: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d ubsequent statem
3780: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 ents are skipped
3790: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 . ^If the 5th p
37a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
37b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
37c0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 not NULL then a
37d0: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 ny error message
37e0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
37f0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
3800: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
3810: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
3820: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f passed back thro
3830: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 ugh the 5th para
3840: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f meter..** To avo
3850: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c id memory leaks,
3860: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
3870: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b should invoke [
3880: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a sqlite3_free()].
3890: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 ** on error mess
38a0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 age strings retu
38b0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 rned through the
38c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 5th parameter o
38d0: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f f.** of sqlite3_
38e0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65 exec() after the
38f0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
3900: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 tring is no long
3910: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 er needed..** ^I
3920: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
3930: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3940: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c xec() is not NUL
3950: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a L and no errors.
3960: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 ** occur, then s
3970: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 qlite3_exec() se
3980: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 ts the pointer i
3990: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 n its 5th parame
39a0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 ter to.** NULL b
39b0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
39c0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 .**.** ^If an sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
39e0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
39f0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 n-zero, the sqli
3a00: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f te3_exec().** ro
3a10: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 utine returns SQ
3a20: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f LITE_ABORT witho
3a30: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 ut invoking the
3a40: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 callback again a
3a50: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 nd.** without ru
3a60: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 nning any subseq
3a70: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 uent SQL stateme
3a80: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
3a90: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 2nd argument to
3aa0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
3ab0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 () callback func
3ac0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e tion is the.** n
3ad0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
3ae0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 in the result.
3af0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 ^The 3rd argume
3b00: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
3b10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 3_exec().** call
3b20: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 back is an array
3b30: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 of pointers to
3b40: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 strings obtained
3b50: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b as if from.** [
3b60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
3b70: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 ext()], one for
3b80: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 each column. ^I
3b90: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 f an element of
3ba0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 a.** result row
3bb0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
3bc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 corresponding s
3bd0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f tring pointer fo
3be0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 r the.** sqlite3
3bf0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
3c00: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
3c10: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 er. ^The 4th ar
3c20: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a gument to the.**
3c30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3c40: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 callback is an a
3c50: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
3c60: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 to strings wher
3c70: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 e each.** entry
3c80: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e represents the n
3c90: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e ame of correspon
3ca0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 ding result colu
3cb0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a mn as obtained.*
3cc0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
3cd0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a column_name()]..
3ce0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e **.** ^If the 2n
3cf0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
3d00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3d10: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
3d20: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
3d30: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
3d40: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 , or a pointer t
3d50: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c hat contains onl
3d60: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 y whitespace and
3d70: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d /or .** SQL comm
3d80: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 ents, then no SQ
3d90: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
3da0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 evaluated and t
3db0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 he database.** i
3dc0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a s not changed..*
3dd0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e *.** Restriction
3de0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
3df0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
3e00: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 ation must insur
3e10: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70 e that the 1st p
3e20: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
3e30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 te3_exec().**
3e40: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e is a valid an
3e50: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 d open [database
3e60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
3e70: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
3e80: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 ation must not c
3e90: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 lose the [databa
3ea0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
3eb0: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 pecified by.**
3ec0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 _exec() while sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
3f00: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e running..** <li>
3f10: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
3f20: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 must not modify
3f30: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
3f40: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 nt text passed i
3f50: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 nto.** the
3f60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
3f70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3f80: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 while sqlite3_ex
3f90: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e ec() is running.
3fa0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 .** </ul>.*/.int
3fb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 sqlite3_exec(.
3fc0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 sqlite3*,
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
3ff0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 n open database
4000: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
4010: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 *sql,
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4030: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 /* SQL to be eva
4040: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 luated */. int
4050: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 (*callback)(void
4060: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 *,int,char**,cha
4070: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 r**), /* Callba
4080: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 ck function */.
4090: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 void *,
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 /* 1
40c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 st argument to c
40d0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 allback */. cha
40e0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 r **errmsg
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4100: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 /* Error
4110: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
4120: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.);../*.** C
4130: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
4140: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 Codes.** KEYWORD
4150: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 S: {result code
4160: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a definitions}.**.
4170: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 ** Many SQLite f
4180: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
4190: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c an integer resul
41a0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 t code from the
41b0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 set shown.** her
41c0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e e in order to in
41d0: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f dicate success o
41e0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a r failure..**.**
41f0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 New error codes
4200: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
4210: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
4220: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
4230: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 * See also: [ext
4240: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
4250: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a e definitions].*
4260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4270: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
4280: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
4290: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 result */./* beg
42a0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d inning-of-error-
42b0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 codes */.#define
42c0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 SQLITE_ERROR
42d0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 1 /* SQL
42e0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 error or missing
42f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
4300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
4310: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 RNAL 2 /*
4320: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 Internal logic e
4330: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a rror in SQLite *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4350: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 _PERM 3
4360: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d /* Access perm
4370: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f ission denied */
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4390: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 ABORT 4
43a0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 /* Callback rou
43b0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 tine requested a
43c0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 n abort */.#defi
43d0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 ne SQLITE_BUSY
43e0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 5 /* Th
43f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
4400: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
4410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
4420: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 ED 6 /*
4430: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 A table in the d
4440: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 atabase is locke
4450: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4460: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ITE_NOMEM
4470: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 7 /* A malloc
4480: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 () failed */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
44a0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 ONLY 8 /*
44b0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 Attempt to write
44c0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 a readonly data
44d0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 base */.#define
44e0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
44f0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 9 /* Opera
4500: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 tion terminated
4510: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 by sqlite3_inter
4520: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 rupt()*/.#define
4530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 SQLITE_IOERR
4540: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 10 /* Some
4550: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f kind of disk I/
4560: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 O error occurred
4570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4580: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 TE_CORRUPT 1
4590: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 1 /* The datab
45a0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 ase disk image i
45b0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 s malformed */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
45d0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f TFOUND 12 /
45e0: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 * Unknown opcode
45f0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 in sqlite3_file
4600: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 _control() */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c efine SQLITE_FUL
4620: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a L 13 /*
4630: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 Insertion faile
4640: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 d because databa
4650: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 se is full */.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
4670: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a TOPEN 14 /*
4680: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 Unable to open
4690: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
46a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
46b0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 ITE_PROTOCOL
46c0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 15 /* Database
46d0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 lock protocol e
46e0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
46f0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 SQLITE_EMPTY
4700: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 16 /* Datab
4710: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a ase is empty */.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
4730: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 CHEMA 17
4740: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 /* The database
4750: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a schema changed *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4770: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 _TOOBIG 18
4780: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 /* String or B
4790: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 LOB exceeds size
47a0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e limit */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
47c0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f INT 19 /* Abo
47d0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 rt due to constr
47e0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a aint violation *
47f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4800: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 _MISMATCH 20
4810: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d /* Data type m
4820: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 ismatch */.#defi
4830: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 ne SQLITE_MISUSE
4840: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 21 /* Li
4850: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 brary used incor
4860: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e rectly */.#defin
4870: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 e SQLITE_NOLFS
4880: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 22 /* Use
4890: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f s OS features no
48a0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 t supported on h
48b0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ost */.#define S
48c0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 QLITE_AUTH
48d0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 23 /* Author
48e0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a ization denied *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4900: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 _FORMAT 24
4910: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 /* Auxiliary d
4920: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 atabase format e
4930: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
4940: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 SQLITE_RANGE
4950: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 25 /* 2nd p
4960: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
4970: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 te3_bind out of
4980: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 range */.#define
4990: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 SQLITE_NOTADB
49a0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 26 /* File
49b0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 opened that is
49c0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 not a database f
49d0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ile */.#define S
49e0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 QLITE_NOTICE
49f0: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 27 /* Notifi
4a00: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c cations from sql
4a10: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 ite3_log() */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 efine SQLITE_WAR
4a30: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a NING 28 /*
4a40: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 Warnings from s
4a50: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a qlite3_log() */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
4a70: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 OW 100
4a80: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
4a90: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f ) has another ro
4aa0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 w ready */.#defi
4ab0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 ne SQLITE_DONE
4ac0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 101 /* sq
4ad0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 lite3_step() has
4ae0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 finished execut
4af0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 ing */./* end-of
4b00: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
4b10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
4b20: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 Extended Result
4b30: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
4b40: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
4b50: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 sult code defini
4b60: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 tions}.**.** In
4b70: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 its default conf
4b80: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 iguration, SQLit
4b90: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 e API routines r
4ba0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 eturn one of 30
4bb0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 integer.** [resu
4bc0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 lt codes]. Howe
4bd0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 ver, experience
4be0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d has shown that m
4bf0: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 any of.** these
4c00: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4c10: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 too coarse-grai
4c20: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f ned. They do no
4c30: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 t provide as.**
4c40: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e much information
4c50: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 about problems
4c60: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d as programmers m
4c70: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 ight like. In a
4c80: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 n effort to.** a
4c90: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 ddress this, new
4ca0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 er versions of S
4cb0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 QLite (version 3
4cc0: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 .3.8 and later)
4cd0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f include.** suppo
4ce0: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rt for additiona
4cf0: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 l result codes t
4d00: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 hat provide more
4d10: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d detailed inform
4d20: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 ation.** about e
4d30: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 rrors. These [ex
4d40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4d50: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 des] are enabled
4d60: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
4d70: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 on a per databas
4d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 e connection bas
4d90: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 is using the.**
4da0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
4db0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
4dc0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 ] API. Or, the
4dd0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f extended code fo
4de0: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 r.** the most re
4df0: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 cent error can b
4e00: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 e obtained using
4e10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
4e20: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d ended_errcode()]
4e30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
4e40: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4e60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
4e70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4e80: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
4e90: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
4ea0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
4eb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4ec0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
4ed0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
4ee0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
4ef0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4f00: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
4f10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4f20: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
4f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4f40: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
4f50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
4f60: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4f80: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
4f90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
4fa0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
4fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4fc0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
4fd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4fe0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
4ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5000: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
5010: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5020: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
5030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5040: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
5050: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5060: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5080: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
5090: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
50a0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
50c0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
50e0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5100: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5120: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5140: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5160: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
5170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5180: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
5190: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
51a0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
51c0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
51e0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5200: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5220: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
5230: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5240: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
5250: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5260: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5280: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
52a0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
52b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
52c0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
52d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
52e0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
52f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5300: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
5310: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5320: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5340: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
5350: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5360: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5380: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
5390: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
53a0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
53c0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 _DELETE_NOENT
53d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
53e0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 | (23<<8)).#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5400: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 _MMAP
5410: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5420: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 | (24<<8)).#def
5430: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5440: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 _GETTEMPPATH
5450: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5460: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 | (25<<8)).#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5480: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
5490: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
54a0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 | (26<<8)).#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
54c0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
54d0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
54e0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
5500: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 _RECOVERY
5510: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 (SQLITE_BUSY
5520: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 | (1<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
5540: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 Y_SNAPSHOT
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 (SQLITE_BUS
5560: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 Y | (2<<8)).#
5570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
5580: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 NTOPEN_NOTEMPDIR
5590: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
55a0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 NTOPEN | (1<<8))
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
55c0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 CANTOPEN_ISDIR
55d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
55e0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 CANTOPEN | (2<<8
55f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5600: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 E_CANTOPEN_FULLP
5610: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 ATH (SQLIT
5620: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c E_CANTOPEN | (3<
5630: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5640: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e ITE_CANTOPEN_CON
5650: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c VPATH (SQL
5660: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
5670: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
5680: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 QLITE_CORRUPT_VT
5690: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 AB (S
56a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 QLITE_CORRUPT |
56b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
56c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
56d0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 RECOVERY (
56e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
56f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5700: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
5710: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 Y_CANTLOCK
5720: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
5730: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 Y | (2<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
5750: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 NLY_ROLLBACK
5760: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
5770: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 NLY | (3<<8)).#d
5780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
5790: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 DONLY_DBMOVED
57a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
57b0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a DONLY | (4<<8)).
57c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
57d0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 BORT_ROLLBACK
57e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 (SQLITE_A
57f0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 BORT | (2<<8)).#
5800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5810: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 NSTRAINT_CHECK
5820: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
5830: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 NSTRAINT | (1<<8
5840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5850: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d E_CONSTRAINT_COM
5860: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 MITHOOK (SQLIT
5870: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5880: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
58a0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 _FOREIGNKEY (S
58b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
58c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
58d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
58e0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 AINT_FUNCTION
58f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
5900: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 AINT | (4<<8)).#
5910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5920: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c NSTRAINT_NOTNULL
5930: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
5940: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 NSTRAINT | (5<<8
5950: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5960: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 E_CONSTRAINT_PRI
5970: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 MARYKEY (SQLIT
5980: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5990: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
59a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
59b0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 _TRIGGER (S
59c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
59d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
59f0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 AINT_UNIQUE
5a00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
5a10: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 AINT | (8<<8)).#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5a30: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 NSTRAINT_VTAB
5a40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
5a50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 NSTRAINT | (9<<8
5a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5a70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 E_CONSTRAINT_ROW
5a80: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 ID (SQLIT
5a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 E_CONSTRAINT |(1
5aa0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 0<<8)).#define S
5ab0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 QLITE_NOTICE_REC
5ac0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 OVER_WAL (S
5ad0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 QLITE_NOTICE | (
5ae0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5af0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 QLITE_NOTICE_REC
5b00: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 OVER_ROLLBACK (S
5b10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 QLITE_NOTICE | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
5b30: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 QLITE_WARNING_AU
5b40: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 TOINDEX (S
5b50: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 QLITE_WARNING |
5b60: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 (1<<8))../*.** C
5b70: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 API3REF: Flags F
5b80: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 or File Open Ope
5b90: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 rations.**.** Th
5ba0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 ese bit values a
5bb0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
5bc0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 use in the.** 3r
5bd0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
5be0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
5bf0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 _v2()] interface
5c00: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 and.** in the 4
5c10: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
5c20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
5c30: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a .xOpen] method..
5c40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5c50: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 E_OPEN_READONLY
5c60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5c70: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 01 /* Ok for sq
5c80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
5c90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5ca0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
5cb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5cc0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 02 /* Ok for sq
5cd0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
5ce0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5cf0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 E_OPEN_CREATE
5d00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5d10: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 04 /* Ok for sq
5d20: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
5d30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5d40: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
5d50: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 LOSE 0x000000
5d60: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 08 /* VFS only
5d70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5d80: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
5d90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5da0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 10 /* VFS only
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5dc0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 E_OPEN_AUTOPROXY
5dd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5de0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 20 /* VFS only
5df0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5e00: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 E_OPEN_URI
5e10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5e20: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 40 /* Ok for sq
5e30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
5e40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5e50: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 E_OPEN_MEMORY
5e60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5e70: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 80 /* Ok for sq
5e80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
5e90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5ea0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 E_OPEN_MAIN_DB
5eb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 0x000001
5ec0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
5ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5ee0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 E_OPEN_TEMP_DB
5ef0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 0x000002
5f00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
5f10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5f20: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
5f30: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 _DB 0x000004
5f40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
5f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5f60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
5f70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 NAL 0x000008
5f80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
5f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5fa0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 E_OPEN_TEMP_JOUR
5fb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 NAL 0x000010
5fc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
5fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5fe0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 E_OPEN_SUBJOURNA
5ff0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 L 0x000020
6000: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6020: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f E_OPEN_MASTER_JO
6030: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 URNAL 0x000040
6040: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6060: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 E_OPEN_NOMUTEX
6070: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 0x000080
6080: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
6090: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
60a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
60b0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
60c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 0x000100
60d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
60e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
60f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6100: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
6110: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 HE 0x000200
6120: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
6130: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
6140: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6150: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
6160: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 CHE 0x000400
6170: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
6180: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
6190: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
61a0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 E_OPEN_WAL
61b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 0x000800
61c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
61d0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a */../* Reserved:
61e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
61f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 0x00F00
6200: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 000 */../*.** CA
6210: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 PI3REF: Device C
6220: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a haracteristics.*
6230: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 *.** The xDevice
6240: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
6250: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 method of the [s
6260: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
6270: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 s].** object ret
6280: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 urns an integer
6290: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f which is a vecto
62a0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 r of these.** bi
62b0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 t values express
62c0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 ing I/O characte
62d0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d ristics of the m
62e0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 ass storage.** d
62f0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 evice that holds
6300: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 the file that t
6310: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
6320: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 ethods].** refer
6330: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 s to..**.** The
6340: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6350: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 MIC property mea
6360: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 ns that all writ
6370: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a es of.** any siz
6380: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 e are atomic. T
6390: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
63a0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 ATOMICnnn values
63b0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 .** mean that wr
63c0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 ites of blocks t
63d0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 hat are nnn byte
63e0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a s in size and.**
63f0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 are aligned to
6400: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 an address which
6410: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d is an integer m
6420: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e ultiple of.** nn
6430: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 n are atomic. T
6440: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
6450: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 SAFE_APPEND valu
6460: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 e means.** that
6470: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 when data is app
6480: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c ended to a file,
6490: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 the data is app
64a0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 ended.** first t
64b0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 hen the size of
64c0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 the file is exte
64d0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 nded, never the
64e0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f other.** way aro
64f0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 und. The SQLITE
6500: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
6510: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 L property means
6520: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 that.** informa
6530: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 tion is written
6540: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 to disk in the s
6550: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c ame order as cal
6560: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 ls.** to xWrite(
6570: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 ). The SQLITE_I
6580: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f OCAP_POWERSAFE_O
6590: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 VERWRITE propert
65a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 y means that.**
65b0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c after reboot fol
65c0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f lowing a crash o
65d0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 r power loss, th
65e0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 e only bytes in
65f0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 a.** file that w
6600: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 ere written at t
6610: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c he application l
6620: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 evel might have
6630: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 changed.** and t
6640: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 hat adjacent byt
6650: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 es, even bytes w
6660: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 ithin the same s
6670: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 ector are.** gua
6680: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e ranteed to be un
6690: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 changed. The SQ
66a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c LITE_IOCAP_UNDEL
66b0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e ETABLE_WHEN_OPEN
66c0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 .** flag indicat
66d0: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 e that a file ca
66e0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 nnot be deleted
66f0: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a when open. The.
6700: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ** SQLITE_IOCAP_
6710: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 IMMUTABLE flag i
6720: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 ndicates that th
6730: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 e file is on.**
6740: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 read-only media
6750: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 and cannot be ch
6760: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 anged even by pr
6770: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 ocesses with.**
6780: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 elevated privile
6790: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ges..*/.#define
67a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
67b0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 MIC
67c0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 0x00000001.#
67d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
67e0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 CAP_ATOMIC512
67f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6800: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
6810: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6820: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C1K
6830: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 0x00000004.#de
6840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6850: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 P_ATOMIC2K
6860: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6870: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 008.#define SQLI
6880: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
6890: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
68a0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
68b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
68c0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 ATOMIC8K
68d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
68e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
68f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
6900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
6910: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 00000040.#define
6920: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6930: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 OMIC32K
6940: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 0x00000080.
6950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6960: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 OCAP_ATOMIC64K
6970: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6980: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
6990: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
69a0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 _APPEND
69b0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 0x00000200.#d
69c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
69d0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 AP_SEQUENTIAL
69e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
69f0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0400.#define SQL
6a00: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 ITE_IOCAP_UNDELE
6a10: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 TABLE_WHEN_OPEN
6a20: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 0x00000800.#def
6a30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6a40: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
6a50: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 RITE 0x000010
6a60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
6a70: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c E_IOCAP_IMMUTABL
6a80: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 E 0
6a90: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a x00002000../*.**
6aa0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 CAPI3REF: File
6ab0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a Locking Levels.*
6ac0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
6ad0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e one of these in
6ae0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 teger values as
6af0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 the second.** ar
6b00: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 gument to calls
6b10: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 it makes to the
6b20: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
6b30: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a ock() methods.**
6b40: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
6b50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
6b60: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ct..*/.#define S
6b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 QLITE_LOCK_NONE
6b80: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
6b90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 ne SQLITE_LOCK_S
6ba0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 HARED 1.#
6bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6bc0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 CK_RESERVED
6bd0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
6be0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 E_LOCK_PENDING
6bf0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
6c00: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
6c10: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a SIVE 4../*.*
6c20: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 * CAPI3REF: Sync
6c30: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 hronization Type
6c40: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 Flags.**.** Whe
6c50: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 n SQLite invokes
6c60: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 the xSync() met
6c70: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 hod of an.** [sq
6c80: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
6c90: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 ] object it uses
6ca0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f a combination o
6cb0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 f.** these integ
6cc0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
6cd0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
6ce0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
6cf0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
6d00: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 AONLY flag is us
6d10: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 ed, it means tha
6d20: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 t the.** sync op
6d30: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 eration only nee
6d40: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 ds to flush data
6d50: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 to mass storage
6d60: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f . Inode.** info
6d70: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 rmation need not
6d80: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 be flushed. If
6d90: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
6da0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a its of the flag.
6db0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ** equal SQLITE_
6dc0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 SYNC_NORMAL, tha
6dd0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e t means to use n
6de0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 ormal fsync() se
6df0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 mantics..** If t
6e00: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
6e10: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ts equal SQLITE_
6e20: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 SYNC_FULL, that
6e30: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 means.** to use
6e40: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 Mac OS X style f
6e50: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 ullsync instead
6e60: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a of fsync()..**.*
6e70: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 * Do not confuse
6e80: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
6e90: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
6ea0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
6eb0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b gs.** with the [
6ec0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
6ed0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b us]=NORMAL and [
6ee0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
6ef0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 us]=FULL.** sett
6f00: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 ings. The [sync
6f10: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 hronous pragma]
6f20: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 determines when
6f30: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 calls to the.**
6f40: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 xSync VFS method
6f50: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 occur and appli
6f60: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 es uniformly acr
6f70: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d oss all platform
6f80: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 s..** The SQLITE
6f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 _SYNC_NORMAL and
6fa0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
6fb0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e L flags determin
6fc0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 e how.** energet
6fd0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f ic or rigorous o
6fe0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 r forceful the s
6ff0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 ync operations a
7000: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d re and.** only m
7010: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 ake a difference
7020: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 on Mac OSX for
7030: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 the default SQLi
7040: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 te code..** (Thi
7050: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 rd-party VFS imp
7060: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 lementations mig
7070: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 ht also make the
7080: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 distinction.**
7090: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 between SQLITE_S
70a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 YNC_NORMAL and S
70b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c QLITE_SYNC_FULL,
70c0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a but among the.*
70d0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 * operating syst
70e0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 ems natively sup
70f0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 ported by SQLite
7100: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a , only Mac OSX.*
7110: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 * cares about th
7120: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a e difference.).*
7130: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
7140: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 _SYNC_NORMAL
7150: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 0x00002.#def
7160: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
7170: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 FULL 0x
7180: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 00003.#define SQ
7190: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
71a0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a LY 0x00010.
71b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
71c0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 OS Interface Op
71d0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a en File Handle.*
71e0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 *.** An [sqlite3
71f0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 _file] object re
7200: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e presents an open
7210: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a file in the .**
7220: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 [sqlite3_vfs |
7230: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 OS interface lay
7240: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c er]. Individual
7250: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a OS interface.**
7260: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
7270: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f will.** want to
7280: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f subclass this o
7290: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 bject by appendi
72a0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 ng additional fi
72b0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 elds.** for thei
72c0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 r own use. The
72d0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 pMethods entry i
72e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
72f0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f n.** [sqlite3_io
7300: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
7310: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 that defines me
7320: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 thods for perfor
7330: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 ming.** I/O oper
7340: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 ations on the op
7350: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 en file..*/.type
7360: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
7370: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f e3_file sqlite3_
7380: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c file;.struct sql
7390: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f ite3_file {. co
73a0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 nst struct sqlit
73b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 e3_io_methods *p
73c0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 Methods; /* Met
73d0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e hods for an open
73e0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a file */.};../*.
73f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
7400: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 Interface File V
7410: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f irtual Methods O
7420: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 bject.**.** Ever
7430: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 y file opened by
7440: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
7450: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 s.xOpen] method
7460: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 populates an.**
7470: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
7480: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 bject (or, more
7490: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 commonly, a subc
74a0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b lass of the.** [
74b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
74c0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 ject) with a poi
74d0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
74e0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
74f0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 ct..** This obje
7500: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d ct defines the m
7510: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 ethods used to p
7520: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f erform various o
7530: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 perations.** aga
7540: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 inst the open fi
7550: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 le represented b
7560: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 y the [sqlite3_f
7570: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a ile] object..**.
7580: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 ** If the [sqlit
7590: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 e3_vfs.xOpen] me
75a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 thod sets the sq
75b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
75c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 ods element .**
75d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f to a non-NULL po
75e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 inter, then the
75f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
7600: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 ds.xClose method
7610: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b .** may be invok
7620: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b ed even if the [
7630: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
7640: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 n] reported that
7650: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 it failed. The
7660: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 .** only way to
7670: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 prevent a call t
7680: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 o xClose followi
7690: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c ng a failed [sql
76a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a ite3_vfs.xOpen].
76b0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 ** is for the [s
76c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
76d0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c ] to set the sql
76e0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
76f0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f ds element.** to
7700: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 NULL..**.** The
7710: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
7720: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 to xSync may be
7730: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 one of [SQLITE_S
7740: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a YNC_NORMAL] or.*
7750: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 * [SQLITE_SYNC_F
7760: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ULL]. The first
7770: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e choice is the n
7780: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a ormal fsync()..*
7790: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f * The second cho
77a0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 ice is a Mac OS
77b0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
77c0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 . The [SQLITE_S
77d0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a YNC_DATAONLY].**
77e0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 flag may be ORe
77f0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 d in to indicate
7800: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 that only the d
7810: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a ata of the file.
7820: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 ** and not its i
7830: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 node needs to be
7840: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 synced..**.** T
7850: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 he integer value
7860: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 s to xLock() and
7870: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f xUnlock() are o
7880: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ne of.** <ul>.**
7890: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
78a0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 CK_NONE],.** <li
78b0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 > [SQLITE_LOCK_S
78c0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 HARED],.** <li>
78d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
78e0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 ERVED],.** <li>
78f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
7900: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 DING], or.** <li
7910: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 > [SQLITE_LOCK_E
7920: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f XCLUSIVE]..** </
7930: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 ul>.** xLock() i
7940: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ncreases the loc
7950: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 k. xUnlock() dec
7960: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
7970: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 .** The xCheckRe
7980: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 servedLock() met
7990: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 hod checks wheth
79a0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 er any database
79b0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 connection,.** e
79c0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 ither in this pr
79d0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 ocess or in some
79e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 other process,
79f0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 is holding a RES
7a00: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e ERVED,.** PENDIN
7a10: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 G, or EXCLUSIVE
7a20: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 lock on the file
7a30: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 . It returns tr
7a40: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 ue.** if such a
7a50: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 lock exists and
7a60: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e false otherwise.
7a70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 .**.** The xFile
7a80: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 Control() method
7a90: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e is a generic in
7aa0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c terface that all
7ab0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 ows custom.** VF
7ac0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
7ad0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f s to directly co
7ae0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 ntrol an open fi
7af0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 le using the.**
7b00: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
7b10: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
7b20: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ce. The second
7b30: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 "op" argument is
7b40: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f an.** integer o
7b50: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 pcode. The thir
7b60: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 d argument is a
7b70: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 generic pointer
7b80: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 intended to.** p
7b90: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 oint to a struct
7ba0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e ure that may con
7bb0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f tain arguments o
7bc0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 r space in which
7bd0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 to.** write ret
7be0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 urn values. Pot
7bf0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 ential uses for
7c00: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d xFileControl() m
7c10: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 ight be.** funct
7c20: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 ions to enable b
7c30: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 locking locks wi
7c40: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 th timeouts, to
7c50: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f change the.** lo
7c60: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 cking strategy (
7c70: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 for example to u
7c80: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b se dot-file lock
7c90: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a s), to inquire.*
7ca0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 * about the stat
7cb0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 us of a lock, or
7cc0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 to break stale
7cd0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 locks. The SQLi
7ce0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 te.** core reser
7cf0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 ves all opcodes
7d00: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f less than 100 fo
7d10: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a r its own use..*
7d20: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f * A [file contro
7d30: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 l opcodes | list
7d40: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 of opcodes] les
7d50: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 s than 100 is av
7d60: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c ailable..** Appl
7d70: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 ications that de
7d80: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 fine a custom xF
7d90: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
7da0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 d should use opc
7db0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 odes.** greater
7dc0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 than 100 to avoi
7dd0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 d conflicts. VF
7de0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
7df0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 s should.** retu
7e00: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f rn [SQLITE_NOTFO
7e10: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f UND] for file co
7e20: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 ntrol opcodes th
7e30: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
7e40: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a * recognize..**.
7e50: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 ** The xSectorSi
7e60: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 ze() method retu
7e70: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 rns the sector s
7e80: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 ize of the.** de
7e90: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c vice that underl
7ea0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 ies the file. T
7eb0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 he sector size i
7ec0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d s the.** minimum
7ed0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 write that can
7ee0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 be performed wit
7ef0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a hout disturbing.
7f00: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 ** other bytes i
7f10: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 n the file. The
7f20: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
7f30: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 ristics().** met
7f40: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 hod returns a bi
7f50: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 t vector describ
7f60: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 ing behaviors of
7f70: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 the.** underlyi
7f80: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a ng device:.**.**
7f90: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
7fa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7fb0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c IC].** <li> [SQL
7fc0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
7fd0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 512].** <li> [SQ
7fe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7ff0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C1K].** <li> [SQ
8000: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8010: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C2K].** <li> [SQ
8020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8030: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C4K].** <li> [SQ
8040: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8050: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C8K].** <li> [SQ
8060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8070: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C16K].** <li> [S
8080: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8090: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC32K].** <li> [
80a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
80b0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC64K].** <li>
80c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 [SQLITE_IOCAP_SA
80d0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c FE_APPEND].** <l
80e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
80f0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 _SEQUENTIAL].**
8100: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
8110: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8120: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 MIC property mea
8130: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 ns that all writ
8140: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a es of.** any siz
8150: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 e are atomic. T
8160: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
8170: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 ATOMICnnn values
8180: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 .** mean that wr
8190: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 ites of blocks t
81a0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 hat are nnn byte
81b0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a s in size and.**
81c0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 are aligned to
81d0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 an address which
81e0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d is an integer m
81f0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e ultiple of.** nn
8200: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 n are atomic. T
8210: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
8220: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 SAFE_APPEND valu
8230: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 e means.** that
8240: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 when data is app
8250: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c ended to a file,
8260: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 the data is app
8270: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 ended.** first t
8280: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 hen the size of
8290: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 the file is exte
82a0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 nded, never the
82b0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f other.** way aro
82c0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 und. The SQLITE
82d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
82e0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 L property means
82f0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 that.** informa
8300: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 tion is written
8310: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 to disk in the s
8320: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c ame order as cal
8330: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 ls.** to xWrite(
8340: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 )..**.** If xRea
8350: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 d() returns SQLI
8360: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
8370: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f EAD it must also
8380: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 fill.** in the
8390: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 unread portions
83a0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 of the buffer wi
83b0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 th zeros. A VFS
83c0: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 that.** fails t
83d0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
83e0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 t reads might se
83f0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 em to work. How
8400: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 ever,.** failure
8410: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
8420: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 ort reads will e
8430: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 ventually lead t
8440: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f o.** database co
8450: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 rruption..*/.typ
8460: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
8470: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 te3_io_methods s
8480: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
8490: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
84a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 3_io_methods {.
84b0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 int iVersion;.
84c0: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 int (*xClose)(s
84d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
84e0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 int (*xRead)(sq
84f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 lite3_file*, voi
8500: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
8510: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
8520: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 t);. int (*xWri
8530: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
8540: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
8550: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
8560: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
8570: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 int (*xTruncat
8580: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
8590: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
85a0: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 size);. int (*x
85b0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 Sync)(sqlite3_fi
85c0: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b le*, int flags);
85d0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 . int (*xFileSi
85e0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ze)(sqlite3_file
85f0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
8600: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 *pSize);. int
8610: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 (*xLock)(sqlite3
8620: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 _file*, int);.
8630: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 int (*xUnlock)(s
8640: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
8650: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 t);. int (*xChe
8660: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 ckReservedLock)(
8670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8680: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 nt *pResOut);.
8690: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 int (*xFileContr
86a0: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ol)(sqlite3_file
86b0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 *, int op, void
86c0: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a *pArg);. int (*
86d0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c xSectorSize)(sql
86e0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
86f0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 nt (*xDeviceChar
8700: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c acteristics)(sql
8710: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f ite3_file*);. /
8720: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 * Methods above
8730: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 are valid for ve
8740: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 rsion 1 */. int
8750: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 (*xShmMap)(sqli
8760: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 te3_file*, int i
8770: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e Pg, int pgsz, in
8780: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 t, void volatile
8790: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 **);. int (*xSh
87a0: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 mLock)(sqlite3_f
87b0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 ile*, int offset
87c0: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 , int n, int fla
87d0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 gs);. void (*xS
87e0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 hmBarrier)(sqlit
87f0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
8800: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 (*xShmUnmap)(sq
8810: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
8820: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 deleteFlag);.
8830: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
8840: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
8850: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e ersion 2 */. in
8860: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 t (*xFetch)(sqli
8870: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
8880: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 e3_int64 iOfst,
8890: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a int iAmt, void *
88a0: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 *pp);. int (*xU
88b0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f nfetch)(sqlite3_
88c0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
88d0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 nt64 iOfst, void
88e0: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f *p);. /* Metho
88f0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
8900: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 id for version 3
8910: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f */. /* Additio
8920: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 nal methods may
8930: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
8940: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d re releases */.}
8950: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
8960: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 F: Standard File
8970: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 Control Opcodes
8980: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 .** KEYWORDS: {f
8990: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f ile control opco
89a0: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 des} {file contr
89b0: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a ol opcode}.**.**
89c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
89d0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 onstants are opc
89e0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 odes for the xFi
89f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
8a00: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
8a10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
8a20: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 object and for t
8a30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
8a40: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 _control()].** i
8a50: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
8a60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
8a70: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 L_LOCKSTATE] opc
8a80: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 ode is used for
8a90: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 debugging. This
8aa0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 .** opcode cause
8ab0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 s the xFileContr
8ac0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 ol method to wri
8ad0: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 te the current s
8ae0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c tate of.** the l
8af0: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c ock (one of [SQL
8b00: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 ITE_LOCK_NONE],
8b10: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 [SQLITE_LOCK_SHA
8b20: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 RED],.** [SQLITE
8b30: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c _LOCK_RESERVED],
8b40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 [SQLITE_LOCK_PE
8b50: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 NDING], or [SQLI
8b60: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
8b70: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 E]).** into an i
8b80: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 nteger that the
8b90: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f pArg argument po
8ba0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 ints to. This ca
8bb0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 pability.** is u
8bc0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 sed during testi
8bd0: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 ng and only need
8be0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 s to be supporte
8bf0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 d when SQLITE_TE
8c00: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 ST.** is defined
8c10: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 ..** <ul>.** <li
8c20: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
8c30: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 SIZE_HINT]].** T
8c40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
8c50: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f _SIZE_HINT] opco
8c60: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 de is used by SQ
8c70: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 Lite to give the
8c80: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 VFS.** layer a
8c90: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 hint of how larg
8ca0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 e the database f
8cb0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f ile will grow to
8cc0: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a be during the.*
8cd0: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 * current transa
8ce0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e ction. This hin
8cf0: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 t is not guarant
8d00: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 eed to be accura
8d10: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 te but it.** is
8d20: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 often close. Th
8d30: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 e underlying VFS
8d40: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f might choose to
8d50: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 preallocate dat
8d60: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 abase.** file sp
8d70: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 ace based on thi
8d80: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 s hint in order
8d90: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 to help writes t
8da0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a o the database.*
8db0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 * file run faste
8dc0: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 r..**.** <li>[[S
8dd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e QLITE_FCNTL_CHUN
8de0: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 K_SIZE]].** The
8df0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 [SQLITE_FCNTL_CH
8e00: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 UNK_SIZE] opcode
8e10: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 is used to requ
8e20: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 est that the VFS
8e30: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 .** extends and
8e40: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 truncates the da
8e50: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 tabase file in c
8e60: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 hunks of a size
8e70: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 specified.** by
8e80: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f the user. The fo
8e90: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f urth argument to
8ea0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
8eb0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 ontrol()] should
8ec0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e .** point to an
8ed0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 integer (type i
8ee0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 nt) containing t
8ef0: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a he new chunk-siz
8f00: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 e to use.** for
8f10: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 the nominated da
8f20: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 tabase. Allocati
8f30: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 ng database file
8f40: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a space in large.
8f50: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 ** chunks (say 1
8f60: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d MB at a time), m
8f70: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 ay reduce file-s
8f80: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 ystem fragmentat
8f90: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f ion and.** impro
8fa0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f ve performance o
8fb0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a n some systems..
8fc0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
8fd0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
8fe0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b INTER]].** The [
8ff0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c SQLITE_FCNTL_FIL
9000: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 E_POINTER] opcod
9010: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 e is used to obt
9020: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a ain a pointer.**
9030: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
9040: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 _file] object as
9050: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 sociated with a
9060: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 particular datab
9070: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
9080: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c n. See the [sql
9090: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
90a0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 l()] documentati
90b0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 on for.** additi
90c0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
90d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
90e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f LITE_FCNTL_SYNC_
90f0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 OMITTED]].** No
9100: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a longer in use..*
9110: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9120: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a E_FCNTL_SYNC]].*
9130: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
9140: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 NTL_SYNC] opcode
9150: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e is generated in
9160: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 ternally by SQLi
9170: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 te and.** sent t
9180: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 o the VFS immedi
9190: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 ately before the
91a0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 xSync method is
91b0: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a invoked on a.**
91c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 database file d
91d0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 escriptor. Or, i
91e0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 f the xSync meth
91f0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 od is not invoke
9200: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 d .** because th
9210: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 e user has confi
9220: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 gured SQLite wit
9230: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 h .** [PRAGMA sy
9240: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 nchronous | PRAG
9250: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f MA synchronous=O
9260: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 FF] it is invoke
9270: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f d in place .** o
9280: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 f the xSync meth
9290: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 od. In most case
92a0: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 s, the pointer a
92b0: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 rgument passed w
92c0: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 ith.** this file
92d0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c -control is NULL
92e0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 . However, if th
92f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
9300: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a is being synced.
9310: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 ** as part of a
9320: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 multi-database c
9330: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d ommit, the argum
9340: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 ent points to a
9350: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a nul-terminated.*
9360: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e * string contain
9370: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 ing the transact
9380: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 ions master-jour
9390: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 nal file name. V
93a0: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f FSes that .** do
93b0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 not need this s
93c0: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c ignal should sil
93d0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 ently ignore thi
93e0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 s opcode. Applic
93f0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c ations .** shoul
9400: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 d not call [sqli
9410: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
9420: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 ()] with this op
9430: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f code as doing so
9440: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 may .** disrupt
9450: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f the operation o
9460: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 f the specialize
9470: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 d VFSes that do
9480: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a require it. .**
9490: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
94a0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 _FCNTL_COMMIT_PH
94b0: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 ASETWO]].** The
94c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f [SQLITE_FCNTL_CO
94d0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f MMIT_PHASETWO] o
94e0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 pcode is generat
94f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
9500: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 SQLite.** and s
9510: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 ent to the VFS a
9520: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 fter a transacti
9530: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d on has been comm
9540: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c itted immediatel
9550: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 y.** but before
9560: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
9570: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 unlocked. VFSes
9580: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 that do not need
9590: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 this signal.**
95a0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 should silently
95b0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f ignore this opco
95c0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 de. Applications
95d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c should not call
95e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
95f0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 e_control()] wit
9600: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 h this opcode as
9610: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 doing so may di
9620: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 srupt the .** op
9630: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 eration of the s
9640: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 pecialized VFSes
9650: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 that do require
9660: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 it. .**.** <li
9670: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
9680: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d WIN32_AV_RETRY]]
9690: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
96a0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
96b0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 RETRY] opcode is
96c0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 used to configu
96d0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 re automatic.**
96e0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 retry counts and
96f0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 intervals for c
9700: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 ertain disk I/O
9710: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 operations for t
9720: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 he.** windows [V
9730: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 FS] in order to
9740: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 provide robustne
9750: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e ss in the presen
9760: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 ce of.** anti-vi
9770: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 rus programs. B
9780: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 y default, the w
9790: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 indows VFS will
97a0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c retry file read,
97b0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 .** file write,
97c0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 and file delete
97d0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f operations up to
97e0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 10 times, with
97f0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 a delay.** of 25
9800: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 milliseconds be
9810: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 fore the first r
9820: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 etry and with th
9830: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 e delay increasi
9840: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 ng.** by an addi
9850: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 tional 25 millis
9860: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 econds with each
9870: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 subsequent retr
9880: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f y. This.** opco
9890: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 de allows these
98a0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 two values (10 r
98b0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 etries and 25 mi
98c0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 lliseconds of de
98d0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 lay).** to be ad
98e0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c justed. The val
98f0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 ues are changed
9900: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 for all database
9910: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 connections.**
9920: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
9930: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 process. The ar
9940: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
9950: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 ter to an array
9960: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 of two.** intege
9970: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 rs where the fir
9980: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 st integer i the
9990: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 new retry count
99a0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a and the second.
99b0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 ** integer is th
99c0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 e delay. If eit
99d0: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e her integer is n
99e0: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
99f0: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 e setting.** is
9a00: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 not changed but
9a10: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f instead the prio
9a20: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 r value of that
9a30: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 setting is writt
9a40: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 en.** into the a
9a50: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f rray entry, allo
9a60: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 wing the current
9a70: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 retry settings
9a80: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f to be.** interro
9a90: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e gated. The zDbN
9aa0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
9ab0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
9ac0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9ad0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d TL_PERSIST_WAL]]
9ae0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
9af0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 _FCNTL_PERSIST_W
9b00: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 AL] opcode is us
9b10: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 ed to set or que
9b20: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 ry the.** persis
9b30: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 tent [WAL | Writ
9b40: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 e Ahead Log] set
9b50: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c ting. By defaul
9b60: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 t, the auxiliary
9b70: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 .** write ahead
9b80: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d log and shared m
9b90: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 emory files used
9ba0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e for transaction
9bb0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 control.** are
9bc0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 automatically de
9bd0: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c leted when the l
9be0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e atest connection
9bf0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
9c00: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 .** closes. Set
9c10: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 ting persistent
9c20: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 WAL mode causes
9c30: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 those files to p
9c40: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 ersist after.**
9c50: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 close. Persisti
9c60: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 ng the files is
9c70: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 useful when othe
9c80: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 r processes that
9c90: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 do not.** have
9ca0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e write permission
9cb0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 on the director
9cc0: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 y containing the
9cd0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
9ce0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 ant.** to read t
9cf0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
9d00: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 , as the WAL and
9d10: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 shared memory f
9d20: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a iles must exist.
9d30: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 ** in order for
9d40: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 the database to
9d50: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 be readable. Th
9d60: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
9d70: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
9d80: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
9d90: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 ] for this opcod
9da0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f e should be a po
9db0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
9dc0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 ger..** That int
9dd0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 eger is 0 to dis
9de0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 able persistent
9df0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f WAL mode or 1 to
9e00: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 enable persiste
9e10: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 nt.** WAL mode.
9e20: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 If the integer
9e30: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 is -1, then it i
9e40: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
9e50: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a th the current.*
9e60: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 * WAL persistenc
9e70: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a e setting..**.**
9e80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9e90: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 NTL_POWERSAFE_OV
9ea0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 ERWRITE]].** ^Th
9eb0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
9ec0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
9ed0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ITE] opcode is u
9ee0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 sed to set or qu
9ef0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 ery the.** persi
9f00: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 stent "powersafe
9f10: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 -overwrite" or "
9f20: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 PSOW" setting.
9f30: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 The PSOW setting
9f40: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 .** determines t
9f50: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 he [SQLITE_IOCAP
9f60: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
9f70: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 RITE] bit of the
9f80: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 .** xDeviceChara
9f90: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f cteristics metho
9fa0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 ds. The fourth p
9fb0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
9fc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
9fd0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 trol()] for this
9fe0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 opcode should b
9ff0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
a000: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 n integer..** Th
a010: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 at integer is 0
a020: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d to disable zero-
a030: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 damage mode or 1
a040: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d to enable zero-
a050: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 damage.** mode.
a060: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 If the integer
a070: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 is -1, then it i
a080: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
a090: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a th the current.*
a0a0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f * zero-damage mo
a0b0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a de setting..**.*
a0c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
a0d0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d CNTL_OVERWRITE]]
a0e0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
a0f0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 _FCNTL_OVERWRITE
a100: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f ] opcode is invo
a110: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 ked by SQLite af
a120: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 ter opening.** a
a130: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 write transacti
a140: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 on to indicate t
a150: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 hat, unless it i
a160: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f s rolled back fo
a170: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e r some.** reason
a180: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 , the entire dat
a190: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 abase file will
a1a0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 be overwritten b
a1b0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a y the current .*
a1c0: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 * transaction. T
a1d0: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 his is used by V
a1e0: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 ACUUM operations
a1f0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
a200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
a210: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ME]].** ^The [SQ
a220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
a230: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 ME] opcode can b
a240: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
a250: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a the names of.**
a260: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 all [VFSes] in
a270: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 the VFS stack.
a280: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 The names are of
a290: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 all VFS shims a
a2a0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 nd the.** final
a2b0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 bottom-level VFS
a2c0: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 are written int
a2d0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
a2e0: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 d from .** [sqli
a2f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e te3_malloc()] an
a300: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 d the result is
a310: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 stored in the ch
a320: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 ar* variable.**
a330: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 that the fourth
a340: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 parameter of [sq
a350: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
a360: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e ol()] points to.
a370: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 .** The caller i
a380: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
a390: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 r freeing the me
a3a0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 mory when done.
a3b0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 As with.** all
a3c0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 file-control act
a3d0: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e ions, there is n
a3e0: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 o guarantee that
a3f0: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 this will actua
a400: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 lly.** do anythi
a410: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f ng. Callers sho
a420: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 uld initialize t
a430: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c he char* variabl
a440: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 e to a NULL.** p
a450: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 ointer in case t
a460: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c his file-control
a470: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e is not implemen
a480: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d ted. This file-
a490: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e control.** is in
a4a0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e tended for diagn
a4b0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a ostic use only..
a4c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
a4d0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
a4e0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 ].** ^Whenever a
a4f0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d [PRAGMA] statem
a500: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 ent is parsed, a
a510: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f n [SQLITE_FCNTL_
a520: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 PRAGMA] .** file
a530: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 control is sent
a540: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 to the open [sq
a550: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
a560: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 ct corresponding
a570: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 .** to the datab
a580: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 ase file to whic
a590: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 h the pragma sta
a5a0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e tement refers. ^
a5b0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 The argument.**
a5c0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 to the [SQLITE_F
a5d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
a5e0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 e control is an
a5f0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e array of.** poin
a600: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
a610: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 (char**) in whic
a620: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 h the second ele
a630: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 ment of the arra
a640: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 y.** is the name
a650: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 of the pragma a
a660: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 nd the third ele
a670: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 ment is the argu
a680: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 ment to the.** p
a690: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 ragma or NULL if
a6a0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 the pragma has
a6b0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 no argument. ^T
a6c0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 he handler for a
a6d0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e n.** [SQLITE_FCN
a6e0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
a6f0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 control can opti
a700: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 onally make the
a710: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a first element.**
a720: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 of the char** a
a730: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f rgument point to
a740: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e a string obtain
a750: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
a760: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f _mprintf()].** o
a770: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 r the equivalent
a780: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 and that string
a790: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 will become the
a7a0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 result of the p
a7b0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 ragma or.** the
a7c0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 error message if
a7d0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c the pragma fail
a7e0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 s. ^If the.** [S
a7f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
a800: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
a810: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
a820: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e _NOTFOUND], then
a830: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 normal .** [PRA
a840: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 GMA] processing
a850: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 continues. ^If
a860: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
a870: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c L_PRAGMA].** fil
a880: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
a890: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
a8a0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 hen the parser a
a8b0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
a8c0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c ** VFS has handl
a8d0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 ed the PRAGMA it
a8e0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 self and the par
a8f0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 ser generates a
a900: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 no-op.** prepare
a910: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 d statement. ^I
a920: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 f the [SQLITE_FC
a930: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
a940: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
a950: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 .** any result c
a960: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ode other than [
a970: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 SQLITE_OK] or [S
a980: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
a990: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 that means.** t
a9a0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f hat the VFS enco
a9b0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 untered an error
a9c0: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 while handling
a9d0: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 the [PRAGMA] and
a9e0: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 the.** compilat
a9f0: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d ion of the PRAGM
aa00: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 A fails with an
aa10: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 error. ^The [SQ
aa20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
aa30: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 A].** file contr
aa40: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 ol occurs at the
aa50: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 beginning of pr
aa60: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 agma statement a
aa70: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a nalysis and so.*
aa80: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 * it is able to
aa90: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 override built-i
aaa0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 n [PRAGMA] state
aab0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ments..**.** <li
aac0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
aad0: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a BUSYHANDLER]].**
aae0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
aaf0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d NTL_BUSYHANDLER]
ab00: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c .** file-control
ab10: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 may be invoked
ab20: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 by SQLite on the
ab30: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 database file h
ab40: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 andle.** shortly
ab50: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 after it is ope
ab60: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ned in order to
ab70: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d provide a custom
ab80: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73 VFS with access
ab90: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 .** to the conne
aba0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 ctions busy-hand
abb0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 ler callback. Th
abc0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 e argument is of
abd0: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a type (void **).
abe0: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 ** - an array of
abf0: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 two (void *) va
ac00: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 lues. The first
ac10: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c (void *) actuall
ac20: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 y points.** to a
ac30: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 function of typ
ac40: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 e (int (*)(void
ac50: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f *)). In order to
ac60: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e invoke the conn
ac70: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d ections.** busy-
ac80: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 handler, this fu
ac90: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 nction should be
aca0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 invoked with th
acb0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a e second (void *
acc0: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 ) in.** the arra
acd0: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 y as the only ar
ace0: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 gument. If it re
acf0: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
ad00: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 then the operati
ad10: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 on.** should be
ad20: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 retried. If it r
ad30: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 eturns zero, the
ad40: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 custom VFS shou
ad50: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a ld abandon the.*
ad60: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 * current operat
ad70: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ion..**.** <li>[
ad80: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 [SQLITE_FCNTL_TE
ad90: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 MPFILENAME]].**
ada0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e ^Application can
adb0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c invoke the [SQL
adc0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 ITE_FCNTL_TEMPFI
add0: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e LENAME] file-con
ade0: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 trol.** to have
adf0: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 SQLite generate
ae00: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 a.** temporary f
ae10: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 ilename using th
ae20: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d e same algorithm
ae30: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 that is followe
ae40: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a d to generate.**
ae50: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e temporary filen
ae60: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 ames for TEMP ta
ae70: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 bles and other i
ae80: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 nternal uses. T
ae90: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 he.** argument s
aea0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a hould be a char*
aeb0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 * which will be
aec0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 filled with the
aed0: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 filename.** writ
aee0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 ten into memory
aef0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
af00: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
af10: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 . The caller sh
af20: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b ould.** invoke [
af30: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
af40: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f on the result to
af50: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 avoid a memory
af60: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e leak..**.** <li>
af70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d [[SQLITE_FCNTL_M
af80: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 MAP_SIZE]].** Th
af90: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
afa0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 MMAP_SIZE] file
afb0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 control is used
afc0: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 to query or set
afd0: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e the.** maximum n
afe0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 umber of bytes t
aff0: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 hat will be used
b000: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 for memory-mapp
b010: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 ed I/O..** The a
b020: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
b030: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 nter to a value
b040: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f of type sqlite3_
b050: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 int64 that.** is
b060: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 an advisory max
b070: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 imum number of b
b080: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 ytes in the file
b090: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 to memory map.
b0a0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 The.** pointer
b0b0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 is overwritten w
b0c0: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 ith the old valu
b0d0: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 e. The limit is
b0e0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a not changed if.
b0f0: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 ** the value ori
b100: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 ginally pointed
b110: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 to is negative,
b120: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 and so the curre
b130: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e nt limit .** can
b140: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70 be queried by p
b150: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e assing in a poin
b160: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 ter to a negativ
b170: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a e number. This.
b180: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 ** file-control
b190: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c is used internal
b1a0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 ly to implement
b1b0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a [PRAGMA mmap_siz
b1c0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b e]..**.** <li>[[
b1d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 SQLITE_FCNTL_TRA
b1e0: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c CE]].** The [SQL
b1f0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d ITE_FCNTL_TRACE]
b200: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 file control pr
b210: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 ovides advisory
b220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 information.** t
b230: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 o the VFS about
b240: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20 what the higher
b250: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 layers of the SQ
b260: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 Lite stack are d
b270: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 oing..** This fi
b280: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 le control is us
b290: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 ed by some VFS a
b2a0: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 ctivity tracing
b2b0: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 [shims]..** The
b2c0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 argument is a ze
b2d0: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
b2e0: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 ring. Higher la
b2f0: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 yers in the.** S
b300: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 QLite stack may
b310: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 generate instanc
b320: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 es of this file
b330: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 control if.** th
b340: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 e [SQLITE_USE_FC
b350: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 NTL_TRACE] compi
b360: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 le-time option i
b370: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a s enabled..**.**
b380: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
b390: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a NTL_HAS_MOVED]].
b3a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
b3b0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 CNTL_HAS_MOVED]
b3c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 file control int
b3d0: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 erprets its argu
b3e0: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 ment as a.** poi
b3f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
b400: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 er and it writes
b410: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 a boolean into
b420: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 that integer dep
b430: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 ending.** on whe
b440: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
b450: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 file has been re
b460: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 named, moved, or
b470: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 deleted since i
b480: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f t.** was first o
b490: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 pened..**.** <li
b4a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
b4b0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 WIN32_SET_HANDLE
b4c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
b4d0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 E_FCNTL_WIN32_SE
b4e0: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 T_HANDLE] opcode
b4f0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 is used for deb
b500: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a ugging. This.**
b510: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 opcode causes t
b520: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 he xFileControl
b530: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 method to swap t
b540: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 he file handle w
b550: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 ith the one.** p
b560: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
b570: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 pArg argument.
b580: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 This capability
b590: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 is used during
b5a0: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f testing.** and o
b5b0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 nly needs to be
b5c0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 supported when S
b5d0: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 QLITE_TEST is de
b5e0: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 fined..**.** </u
b5f0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
b600: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
b610: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 TATE
b620: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
b630: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 ITE_GET_LOCKPROX
b640: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 YFILE
b650: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
b660: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_SET_LOCKPROXY
b670: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 FILE
b680: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
b690: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 E_LAST_ERRNO
b6a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b6b0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
b6c0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 _FCNTL_SIZE_HINT
b6d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 5
b6e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
b6f0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
b700: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 6.
b710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
b720: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
b730: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 R 7.#
b740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
b750: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 NTL_SYNC_OMITTED
b760: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 8.#d
b770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
b780: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 TL_WIN32_AV_RETR
b790: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 Y 9.#de
b7a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
b7b0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 L_PERSIST_WAL
b7c0: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 10.#def
b7d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
b7e0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 _OVERWRITE
b7f0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 11.#defi
b800: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
b810: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 VFSNAME
b820: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 12.#defin
b830: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
b840: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
b850: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 TE 13.#define
b860: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 SQLITE_FCNTL_PR
b870: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 AGMA
b880: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 14.#define
b890: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 SQLITE_FCNTL_BUS
b8a0: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 YHANDLER
b8b0: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 15.#define S
b8c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 QLITE_FCNTL_TEMP
b8d0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 FILENAME
b8e0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 16.#define SQ
b8f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f LITE_FCNTL_MMAP_
b900: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 SIZE
b910: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 18.#define SQL
b920: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 ITE_FCNTL_TRACE
b930: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b940: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 19.#define SQLI
b950: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 TE_FCNTL_HAS_MOV
b960: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ED
b970: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 20.#define SQLIT
b980: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 E_FCNTL_SYNC
b990: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
b9a0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
b9b0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 _FCNTL_COMMIT_PH
b9c0: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 ASETWO 22
b9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
b9e0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f FCNTL_WIN32_SET_
b9f0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a HANDLE 23.
ba00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
ba10: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a Mutex Handle.**
ba20: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
ba30: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
ba40: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
ba50: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
ba60: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
ba70: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
ba80: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
ba90: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
baa0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
bab0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
bac0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
bad0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
bae0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
baf0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
bb00: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
bb10: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
bb20: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
bb30: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
bb40: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
bb50: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
bb60: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
bb70: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
bb80: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
bb90: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
bba0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ace Object.**.**
bbb0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
bbc0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
bbd0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
bbe0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
bbf0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 ween.** the SQLi
bc00: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 te core and the
bc10: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
bc20: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 ting system. Th
bc30: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 e "vfs".** in th
bc40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 e name of the ob
bc50: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 ject stands for
bc60: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 "virtual file sy
bc70: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 stem". See.** t
bc80: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f he [VFS | VFS do
bc90: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
bca0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 further informa
bcb0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
bcc0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 value of the iVe
bcd0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 rsion field is i
bce0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d nitially 1 but m
bcf0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a ay be larger in.
bd00: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f ** future versio
bd10: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 ns of SQLite. A
bd20: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
bd30: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
bd40: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 to this.** obje
bd50: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 ct when the iVer
bd60: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e sion value is in
bd70: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 creased. Note t
bd80: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
bd90: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
bda0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
bdb0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
bdc0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 ansaction betwee
bdd0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 n.** SQLite vers
bde0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e ion 3.5.9 and 3.
bdf0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 6.0 and yet the
be00: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 iVersion field w
be10: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 as not.** modifi
be20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
be30: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
be40: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
be50: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 subclassed [sqli
be60: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 te3_file].** str
be70: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 ucture used by t
be80: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 his VFS. mxPath
be90: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 name is the maxi
bea0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a mum length of.**
beb0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 a pathname in t
bec0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 his VFS..**.** R
bed0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 egistered sqlite
bee0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 3_vfs objects ar
bef0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b e kept on a link
bf00: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 ed list formed b
bf10: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 y.** the pNext p
bf20: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 ointer. The [sq
bf30: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
bf40: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 er()].** and [sq
bf50: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
bf60: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 ster()] interfac
bf70: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c es manage this l
bf80: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 ist.** in a thre
bf90: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 ad-safe way. Th
bfa0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 e [sqlite3_vfs_f
bfb0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ind()] interface
bfc0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 .** searches the
bfd0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 list. Neither
bfe0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
bff0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 code nor the VFS
c000: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
c010: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 on should use th
c020: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
c030: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 .**.** The pNext
c040: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e field is the on
c050: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 ly field in the
c060: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 sqlite3_vfs.** s
c070: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 tructure that SQ
c080: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d Lite will ever m
c090: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 odify. SQLite w
c0a0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a ill only access.
c0b0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ** or modify thi
c0c0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f s field while ho
c0d0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c lding a particul
c0e0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e ar static mutex.
c0f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
c100: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
c110: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 modify anything
c120: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 within the sqli
c130: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 te3_vfs.** objec
c140: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 t once the objec
c150: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 t has been regis
c160: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tered..**.** The
c170: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c zName field hol
c180: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ds the name of t
c190: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 he VFS module.
c1a0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a The name must.**
c1b0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 be unique acros
c1c0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 s all VFS module
c1d0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 s..**.** [[sqlit
c1e0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a e3_vfs.xOpen]].*
c1f0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e * ^SQLite guaran
c200: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 tees that the zF
c210: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
c220: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 r to xOpen.** is
c230: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
c240: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 ointer or string
c250: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
c260: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 m xFullPathname(
c270: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e ) with an option
c280: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e al suffix added.
c290: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 .** ^If a suffix
c2a0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 is added to the
c2b0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
c2c0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a eter, it will.**
c2d0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 consist of a si
c2e0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 ngle "-" charact
c2f0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e er followed by n
c300: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 o more than.** 1
c310: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 1 alphanumeric a
c320: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 nd/or "-" charac
c330: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 ters..** ^SQLite
c340: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 further guarant
c350: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ees that.** the
c360: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 string will be v
c370: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 alid and unchang
c380: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 ed until xClose(
c390: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 ) is.** called.
c3a0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 Because of the p
c3b0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
c3c0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 ,.** the [sqlite
c3d0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 3_file] can safe
c3e0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 ly store a point
c3f0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c er to the.** fil
c400: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 ename if it need
c410: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 s to remember th
c420: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 e filename for s
c430: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 ome reason..** I
c440: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 f the zFilename
c450: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
c460: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 en is a NULL poi
c470: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a nter then xOpen.
c480: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 ** must invent i
c490: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 ts own temporary
c4a0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 name for the fi
c4b0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 le. ^Whenever t
c4c0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
c4d0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
c4e0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
c4f0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
c500: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
c510: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
c520: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
c530: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
c540: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
c550: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
c560: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
c570: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
c580: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
c590: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
c5a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
c5b0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
c5c0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
c5d0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
c5e0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
c5f0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
c600: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
c610: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
c620: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
c630: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
c640: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
c650: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
c660: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
c670: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
c680: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
c690: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
c6a0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
c6b0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
c6c0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 .**.** ^(SQLite
c6d0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e will also add on
c6e0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
c6f0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
c700: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c xOpen().** call,
c710: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
c720: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f e object being o
c730: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c pened:.**.** <ul
c740: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 >.** <li> [SQLI
c750: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
c760: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
c770: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
c780: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
c790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
c7a0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
c7b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
c7c0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
c7d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 [SQLITE_OPEN_TR
c7e0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c ANSIENT_DB].** <
c7f0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
c800: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a N_SUBJOURNAL].**
c810: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
c820: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
c830: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
c840: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a LITE_OPEN_WAL].*
c850: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
c860: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 The file I/O imp
c870: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 lementation can
c880: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 use the object t
c890: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 ype flags to.**
c8a0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 change the way i
c8b0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c t deals with fil
c8c0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 es. For example
c8d0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
c8e0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f .** that does no
c8f0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 t care about cra
c900: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 sh recovery or r
c910: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 ollback might ma
c920: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f ke.** the open o
c930: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 f a journal file
c940: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 a no-op. Write
c950: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 s to this journa
c960: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 l would.** also
c970: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 be no-ops, and a
c980: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 ny attempt to re
c990: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 ad the journal w
c9a0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 ould return.** S
c9b0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 QLITE_IOERR. Or
c9c0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
c9d0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e ion might recogn
c9e0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 ize that a datab
c9f0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c ase.** file will
ca00: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 be doing page-a
ca10: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 ligned sector re
ca20: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 ads and writes i
ca30: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 n a random.** or
ca40: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 der and set up i
ca50: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d ts I/O subsystem
ca60: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a accordingly..**
ca70: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 .** SQLite might
ca80: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
ca90: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
caa0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
cab0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 n method:.**.**
cac0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
cad0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
cae0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
caf0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
cb00: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
cb10: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c >.**.** The [SQL
cb20: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
cb30: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 NCLOSE] flag mea
cb40: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
cb50: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 ld be.** deleted
cb60: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 when it is clos
cb70: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 ed. ^The [SQLIT
cb80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
cb90: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
cba0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 set for TEMP da
cbb0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 tabases and thei
cbc0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e r journals, tran
cbd0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 sient.** databas
cbe0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e es, and subjourn
cbf0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 als..**.** ^The
cc00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
cc10: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 LUSIVE] flag is
cc20: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 always used in c
cc30: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 onjunction.** wi
cc40: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
cc50: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 PEN_CREATE] flag
cc60: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 , which are both
cc70: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 directly.** ana
cc80: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f logous to the O_
cc90: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 EXCL and O_CREAT
cca0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f flags of the PO
ccb0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 SIX open().** AP
ccc0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f I. The SQLITE_O
ccd0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c PEN_EXCLUSIVE fl
cce0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 ag, when paired
ccf0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c with the .** SQL
cd00: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c ITE_OPEN_CREATE,
cd10: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 is used to indi
cd20: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 cate that file s
cd30: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 hould always.**
cd40: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 be created, and
cd50: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 that it is an er
cd60: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 ror if it alread
cd70: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 y exists..** It
cd80: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 is <i>not</i> us
cd90: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
cda0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
cdb0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 e opened .** for
cdc0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 exclusive acces
cdd0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 s..**.** ^At lea
cde0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 st szOsFile byte
cdf0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 s of memory are
ce00: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
ce10: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 ite.** to hold t
ce20: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c he [sqlite3_fil
ce30: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 e] structure pas
ce40: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
ce50: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 .** argument to
ce60: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 xOpen. The xOpe
ce70: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f n method does no
ce80: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c t have to.** all
ce90: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 ocate the struct
cea0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a ure; it should j
ceb0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 ust fill it in.
cec0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 Note that.** th
ced0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d e xOpen method m
cee0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 ust set the sqli
cef0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
cf00: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 s to either.** a
cf10: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f valid [sqlite3_
cf20: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
cf30: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 ct or to NULL.
cf40: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a xOpen must do.**
cf50: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 this even if th
cf60: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 e open fails. S
cf70: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 QLite expects th
cf80: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 at the sqlite3_f
cf90: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 ile.pMethods.**
cfa0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 element will be
cfb0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 valid after xOpe
cfc0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 n returns regard
cfd0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 less of the succ
cfe0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 ess.** or failur
cff0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 e of the xOpen c
d000: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c all..**.** [[sql
d010: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 ite3_vfs.xAccess
d020: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 ]].** ^The flags
d030: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 argument to xAc
d040: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 cess() may be [S
d050: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
d060: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 STS].** to test
d070: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 for the existenc
d080: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 e of a file, or
d090: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
d0a0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 EADWRITE] to.**
d0b0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
d0c0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 ile is readable
d0d0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 and writable, or
d0e0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
d0f0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 READ].** to test
d100: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
d110: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 is at least read
d120: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 able. The file
d130: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 can be a.** dir
d140: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 ectory..**.** ^S
d150: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 QLite will alway
d160: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 s allocate at le
d170: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 ast mxPathname+1
d180: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a bytes for the.*
d190: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 * output buffer
d1a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 xFullPathname.
d1b0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f The exact size o
d1c0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
d1d0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 fer.** is also p
d1e0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d assed as a param
d1f0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 eter to both me
d200: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
d210: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
d220: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
d230: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 gh, [SQLITE_CANT
d240: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 OPEN] should be
d250: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 returned. Since
d260: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c this is.** handl
d270: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 ed as a fatal er
d280: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 ror by SQLite, v
d290: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f fs implementatio
d2a0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 ns should endeav
d2b0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 or.** to prevent
d2c0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 this by setting
d2d0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 mxPathname to a
d2e0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 sufficiently la
d2f0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a rge value..**.**
d300: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
d310: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 (), xSleep(), xC
d320: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e urrentTime(), an
d330: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e d xCurrentTimeIn
d340: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 t64().** interfa
d350: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 ces are not stri
d360: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 ctly a part of t
d370: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 he filesystem, b
d380: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 ut they are.** i
d390: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 ncluded in the V
d3a0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 FS structure for
d3b0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a completeness..*
d3c0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
d3d0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 s() function att
d3e0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 empts to return
d3f0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 nBytes bytes.**
d400: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 of good-quality
d410: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
d420: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 zOut. The retur
d430: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 n value is.** th
d440: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 e actual number
d450: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 of bytes of rand
d460: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e omness obtained.
d470: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 .** The xSleep()
d480: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 method causes t
d490: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 he calling threa
d4a0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 d to sleep for a
d4b0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e t.** least the n
d4c0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 umber of microse
d4d0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 conds given. ^T
d4e0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 he xCurrentTime(
d4f0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
d500: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 rns a Julian Day
d510: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 Number for the
d520: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 current date and
d530: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c time as.** a fl
d540: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
d550: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 ue..** ^The xCur
d560: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
d570: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 method returns,
d580: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 as an integer, t
d590: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 he Julian.** Day
d5a0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 Number multipli
d5b0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 ed by 86400000 (
d5c0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
d5d0: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a lliseconds in .*
d5e0: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 * a 24-hour day)
d5f0: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 . .** ^SQLite w
d600: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 ill use the xCur
d610: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
d620: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 method to get th
d630: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 e current.** dat
d640: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 e and time if th
d650: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 at method is ava
d660: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 ilable (if iVers
d670: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 ion is 2 or .**
d680: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 greater and the
d690: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
d6a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e is not NULL) an
d6b0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b d will fall back
d6c0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 .** to xCurrentT
d6d0: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e ime() if xCurren
d6e0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 tTimeInt64() is
d6f0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a unavailable..**.
d700: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 ** ^The xSetSyst
d710: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 emCall(), xGetSy
d720: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 stemCall(), and
d730: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 xNestSystemCall(
d740: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
d750: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 are not used by
d760: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e the SQLite core.
d770: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c These optional
d780: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
d790: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 provided.** by s
d7a0: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 ome VFSes to fac
d7b0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 ilitate testing
d7c0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e of the VFS code.
d7d0: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a By overriding .
d7e0: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 ** system calls
d7f0: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 with functions u
d800: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c nder its control
d810: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d , a test program
d820: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 can.** simulate
d830: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f faults and erro
d840: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 r conditions tha
d850: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 t would otherwis
d860: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a e be difficult.*
d870: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 * or impossible
d880: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 to induce. The
d890: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 set of system ca
d8a0: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 lls that can be
d8b0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 overridden.** va
d8c0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 ries from one VF
d8d0: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e S to another, an
d8e0: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 d from one versi
d8f0: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 on of the same V
d900: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 FS to the.** nex
d910: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 t. Applications
d920: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 that use these
d930: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 interfaces must
d940: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 be prepared for
d950: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 any.** or all of
d960: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
d970: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 s to be NULL or
d980: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 for their behavi
d990: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 or to change.**
d9a0: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 from one release
d9b0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 to the next. A
d9c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 pplications must
d9d0: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 not attempt to
d9e0: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 access.** any of
d9f0: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 these methods i
da00: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f f the iVersion o
da10: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 f the VFS is les
da20: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 s than 3..*/.typ
da30: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
da40: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f te3_vfs sqlite3_
da50: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 vfs;.typedef voi
da60: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 d (*sqlite3_sysc
da70: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a all_ptr)(void);.
da80: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
da90: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 fs {. int iVers
daa0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 ion;
dab0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 /* Structure ver
dac0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 sion number (cur
dad0: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 rently 3) */. i
dae0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 nt szOsFile;
daf0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 /* Size
db00: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 of subclassed sq
db10: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 lite3_file */.
db20: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 int mxPathname;
db30: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
db40: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d mum file pathnam
db50: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 e length */. sq
db60: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 lite3_vfs *pNext
db70: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 ; /* Next r
db80: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f egistered VFS */
db90: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
dba0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e Name; /* N
dbb0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 ame of this virt
dbc0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 ual file system
dbd0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
dbe0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ata; /*
dbf0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c Pointer to appl
dc00: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 ication-specific
dc10: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 data */. int (
dc20: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f *xOpen)(sqlite3_
dc30: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
dc40: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
dc50: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 _file*,.
dc60: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 int flags
dc70: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 , int *pOutFlags
dc80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 );. int (*xDele
dc90: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a te)(sqlite3_vfs*
dca0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
dcb0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 ame, int syncDir
dcc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 );. int (*xAcce
dcd0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
dce0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
dcf0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 ame, int flags,
dd00: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
dd10: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 int (*xFullPath
dd20: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 name)(sqlite3_vf
dd30: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
dd40: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c zName, int nOut,
dd50: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
dd60: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 void *(*xDlOpen)
dd70: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
dd80: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
dd90: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a name);. void (*
dda0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 xDlError)(sqlite
ddb0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
ddc0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 e, char *zErrMsg
ddd0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 );. void (*(*xD
dde0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 lSym)(sqlite3_vf
ddf0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 s*,void*, const
de00: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 char *zSymbol))(
de10: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a void);. void (*
de20: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 xDlClose)(sqlite
de30: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 3_vfs*, void*);.
de40: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e int (*xRandomn
de50: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
de60: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
de70: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 ar *zOut);. int
de80: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 (*xSleep)(sqlit
de90: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 e3_vfs*, int mic
dea0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e roseconds);. in
deb0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
dec0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
ded0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 double*);. int
dee0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 (*xGetLastError)
def0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
df00: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f nt, char *);. /
df10: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
df20: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
df30: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 version 1 of the
df40: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
df50: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 ct. ** definiti
df60: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 on. Those that
df70: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 follow are added
df80: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 in version 2 or
df90: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e later. */. in
dfa0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
dfb0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 Int64)(sqlite3_v
dfc0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 fs*, sqlite3_int
dfd0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 64*);. /*. **
dfe0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
dff0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
e000: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 s 1 and 2 of the
e010: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
e020: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 ct.. ** Those b
e030: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 elow are for ver
e040: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 sion 3 and great
e050: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 er.. */. int (
e060: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xSetSystemCall)
e070: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
e080: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
e090: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c , sqlite3_syscal
e0a0: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 l_ptr);. sqlite
e0b0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 3_syscall_ptr (*
e0c0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xGetSystemCall)(
e0d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
e0e0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
e0f0: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ;. const char *
e100: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c (*xNextSystemCal
e110: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
e120: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
e130: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 me);. /*. ** T
e140: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
e150: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
e160: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 1 through 3 of
e170: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f the sqlite_vfs o
e180: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 bject.. ** New
e190: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
e1a0: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 pended in figure
e1b0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 versions. The
e1c0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 iVersion. ** va
e1d0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 lue will increme
e1e0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 nt whenever this
e1f0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a happens. . */.
e200: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
e210: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 EF: Flags for th
e220: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 e xAccess VFS me
e230: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 thod.**.** These
e240: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
e250: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 ts can be used a
e260: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 s the third para
e270: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
e280: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f xAccess method o
e290: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 f an [sqlite3_vf
e2a0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 s] object. They
e2b0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 determine.** wh
e2c0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 at kind of permi
e2d0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 ssions the xAcce
e2e0: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f ss method is loo
e2f0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 king for..** Wit
e300: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
e310: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 EXISTS, the xAcc
e320: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 ess method.** si
e330: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 mply checks whet
e340: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 her the file exi
e350: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c sts..** With SQL
e360: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
e370: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 RITE, the xAcces
e380: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
e390: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e ks whether the n
e3a0: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 amed directory i
e3b0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 s both readable
e3c0: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 and writable.**
e3d0: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c (in other words,
e3e0: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 if files can be
e3f0: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c added, removed,
e400: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 and renamed wit
e410: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 hin.** the direc
e420: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 tory)..** The SQ
e430: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
e440: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 WRITE constant i
e450: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 s currently used
e460: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 only by the.**
e470: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
e480: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 ctory pragma], t
e490: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 hough this could
e4a0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 change in a fut
e4b0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f ure.** release o
e4c0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 f SQLite..** Wit
e4d0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
e4e0: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 READ, the xAcces
e4f0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
e500: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
e510: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e ile is readable.
e520: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 The SQLITE_ACC
e530: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e ESS_READ constan
e540: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c t is.** currentl
e550: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 y unused, though
e560: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 it might be use
e570: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 d in a future re
e580: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
e590: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
e5a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
e5b0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 STS 0.#define
e5c0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
e5d0: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 EADWRITE 1 /*
e5e0: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 Used by PRAGMA t
e5f0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
e600: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ory */.#define S
e610: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
e620: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e D 2 /* Un
e630: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
e640: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 API3REF: Flags f
e650: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 or the xShmLock
e660: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
e670: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
e680: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
e690: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b the various lock
e6a0: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a ing operations.*
e6b0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 * allowed by the
e6c0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
e6d0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f of [sqlite3_io_
e6e0: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a methods]. The.*
e6f0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 * following are
e700: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 the only legal c
e710: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 ombinations of f
e720: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 lags to the.** x
e730: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a ShmLock method:.
e740: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
e750: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c i> SQLITE_SHM_L
e760: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
e770: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
e780: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
e790: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
e7a0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 CLUSIVE.** <li>
e7b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
e7c0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
e7d0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
e7e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
e7f0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
e800: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c XCLUSIVE.** </ul
e810: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c >.**.** When unl
e820: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 ocking, the same
e830: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 SHARED or EXCLU
e840: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 SIVE flag must b
e850: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a e supplied as.**
e860: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 was given no th
e870: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
e880: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 lock. .**.** Th
e890: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
e8a0: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e d can transition
e8b0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 between unlocke
e8c0: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a d and SHARED or.
e8d0: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 ** between unloc
e8e0: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 ked and EXCLUSIV
e8f0: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 E. It cannot tr
e900: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
e910: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 SHARED.** and E
e920: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 XCLUSIVE..*/.#de
e930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
e940: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 UNLOCK 1.#
e950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
e960: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 M_LOCK 2
e970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e980: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 SHM_SHARED
e990: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
e9a0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 E_SHM_EXCLUSIVE
e9b0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8../*.** CAPI
e9c0: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 3REF: Maximum xS
e9d0: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a hmLock index.**.
e9e0: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 ** The xShmLock
e9f0: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 method on [sqlit
ea00: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d e3_io_methods] m
ea10: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a ay use values.**
ea20: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 between 0 and t
ea30: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 his upper bound
ea40: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 as its "offset"
ea50: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
ea60: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c SQLite core wil
ea70: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 l never attempt
ea80: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 to acquire or re
ea90: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 lease a.** lock
eaa0: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 outside of this
eab0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 range.*/.#define
eac0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 SQLITE_SHM_NLOC
ead0: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a K 8.../*.
eae0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 ** CAPI3REF: Ini
eaf0: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 tialize The SQLi
eb00: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
eb10: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
eb20: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
eb30: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 ne initializes t
eb40: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 he.** SQLite lib
eb50: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 rary. ^The sqli
eb60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 te3_shutdown() r
eb70: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f outine.** deallo
eb80: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 cates any resour
eb90: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c ces that were al
eba0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
ebb0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
ebc0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
ebd0: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 es are designed
ebe0: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 to aid in proces
ebf0: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
ec00: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e and.** shutdown
ec10: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 on embedded sys
ec20: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 tems. Workstati
ec30: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 on applications
ec40: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 using.** SQLite
ec50: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 normally do not
ec60: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 need to invoke e
ec70: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 ither of these r
ec80: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 outines..**.** A
ec90: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
eca0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
ecb0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 an "effective"
ecc0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a call if it is.**
ecd0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
ece0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
ecf0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ze() is invoked
ed00: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 during the lifet
ed10: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 ime of.** the pr
ed20: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 ocess, or if it
ed30: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d is the first tim
ed40: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
ed50: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
ed60: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 d.** following a
ed70: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
ed80: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 _shutdown(). ^(
ed90: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 Only an effectiv
eda0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c e call.** of sql
edb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
edc0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 ) does any initi
edd0: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 alization. All
ede0: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 other calls.** a
edf0: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
ee00: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ps.)^.**.** A ca
ee10: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
ee20: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 utdown() is an "
ee30: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
ee40: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
ee50: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 st.** call to sq
ee60: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
ee70: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 since the last
ee80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
ee90: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a ze(). ^(Only.**
eea0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
eeb0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
eec0: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e utdown() does an
eed0: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 y deinitializati
eee0: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 on..** All other
eef0: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 valid calls to
ef00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
ef10: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 () are harmless
ef20: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 no-ops.)^.**.**
ef30: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
ef40: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 ialize() interfa
ef50: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 ce is threadsafe
ef60: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 , but sqlite3_sh
ef70: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e utdown().** is n
ef80: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ot. The sqlite3
ef90: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 _shutdown() inte
efa0: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 rface must only
efb0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 be called from a
efc0: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 .** single threa
efd0: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 d. All open [da
efe0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
eff0: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 ns] must be clos
f000: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 ed and all.** ot
f010: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 her SQLite resou
f020: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 rces must be dea
f030: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 llocated prior t
f040: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 o invoking.** sq
f050: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f060: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 ..**.** Among ot
f070: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c her things, ^sql
f080: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f090: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a ) will invoke.**
f0a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
f0b0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 (). Similarly,
f0c0: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 ^sqlite3_shutdow
f0d0: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f n().** will invo
f0e0: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ke sqlite3_os_en
f0f0: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 d()..**.** ^The
f100: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
f110: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 ze() routine ret
f120: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
f130: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 on success..**
f140: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ^If for some rea
f150: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 son, sqlite3_ini
f160: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 tialize() is una
f170: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a ble to initializ
f180: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 e.** the library
f190: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 (perhaps it is
f1a0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
f1b0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f te a needed reso
f1c0: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 urce such.** as
f1d0: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 a mutex) it retu
f1e0: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f rns an [error co
f1f0: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b de] other than [
f200: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
f210: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
f220: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
f230: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e ine is called in
f240: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 ternally by many
f250: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 other.** SQLite
f260: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 interfaces so t
f270: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 hat an applicati
f280: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 on usually does
f290: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 not need to.** i
f2a0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e nvoke sqlite3_in
f2b0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
f2c0: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c tly. For exampl
f2d0: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e e, [sqlite3_open
f2e0: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c ()].** calls sql
f2f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f300: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 ) so the SQLite
f310: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 library will be
f320: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
f330: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 initialized whe
f340: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 n [sqlite3_open(
f350: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 )] is called if
f360: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e it has not be in
f370: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 itialized.** alr
f380: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c eady. ^However,
f390: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
f3a0: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
f3b0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
f3c0: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c OINIT].** compil
f3d0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 e-time option, t
f3e0: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 hen the automati
f3f0: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 c calls to sqlit
f400: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
f410: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 ** are omitted a
f420: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
f430: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c on must call sql
f440: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f450: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 ) directly.** pr
f460: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 ior to using any
f470: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
f480: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 terface. For ma
f490: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 ximum portabilit
f4a0: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f y,.** it is reco
f4b0: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
f4c0: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 lications always
f4d0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
f4e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 initialize().**
f4f0: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 directly prior t
f500: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
f510: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
f520: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 ce. Future rele
f530: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ases.** of SQLit
f540: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 e may require th
f550: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f is. In other wo
f560: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f rds, the behavio
f570: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 r exhibited.** w
f580: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
f590: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c mpiled with [SQL
f5a0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
f5b0: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 T] might become
f5c0: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 the.** default b
f5d0: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 ehavior in some
f5e0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
f5f0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
f600: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
f610: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f nit() routine do
f620: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 es operating-sys
f630: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 tem specific.**
f640: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
f650: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 f the SQLite lib
f660: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 rary. The sqlit
f670: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 e3_os_end().** r
f680: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 outine undoes th
f690: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 e effect of sqli
f6a0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
f6b0: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a Typical tasks.**
f6c0: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 performed by th
f6d0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 ese routines inc
f6e0: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 lude allocation
f6f0: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a or deallocation.
f700: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 ** of static res
f710: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 ources, initiali
f720: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c zation of global
f730: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 variables,.** s
f740: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 etting up a defa
f750: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
f760: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 ] module, or set
f770: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 ting up.** a def
f780: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
f790: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 on using [sqlite
f7a0: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 3_config()]..**.
f7b0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
f7c0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
f7d0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 invoke either sq
f7e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a lite3_os_init().
f7f0: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 ** or sqlite3_os
f800: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e _end() directly.
f810: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
f820: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e n should only in
f830: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
f840: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 initialize() and
f850: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f860: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 n(). The sqlite
f870: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 3_os_init().** i
f880: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c nterface is call
f890: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
f8a0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
f8b0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 ialize() and.**
f8c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
f8d0: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 is called by sq
f8e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f8f0: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a . Appropriate.*
f900: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
f910: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 s for sqlite3_os
f920: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 _init() and sqli
f930: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
f940: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 are built into S
f950: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 QLite when it is
f960: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e compiled for Un
f970: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 ix, Windows, or
f980: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 OS/2..** When [c
f990: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 ustom builds | b
f9a0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
f9b0: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 latforms].** (us
f9c0: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
f9d0: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 OS_OTHER=1] comp
f9e0: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
f9f0: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 on) the applicat
fa00: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 ion must supply
fa10: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 a suitable imple
fa20: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
fa30: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
fa40: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
fa50: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 s_end(). An app
fa60: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 lication-supplie
fa70: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 d.** implementat
fa80: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ion of sqlite3_o
fa90: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 s_init() or sqli
faa0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
fab0: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c must return [SQL
fac0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
fad0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 ss and some othe
fae0: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 r [error code] u
faf0: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a pon.** failure..
fb00: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 */.int sqlite3_i
fb10: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b nitialize(void);
fb20: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 .int sqlite3_shu
fb30: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 tdown(void);.int
fb40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
fb50: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
fb60: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 te3_os_end(void)
fb70: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
fb80: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 F: Configuring T
fb90: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
fba0: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 y.**.** The sqli
fbb0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 te3_config() int
fbc0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
fbd0: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f o make global co
fbe0: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 nfiguration.** c
fbf0: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 hanges to SQLite
fc00: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e in order to tun
fc10: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 e SQLite to the
fc20: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f specific needs o
fc30: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 f.** the applica
fc40: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 tion. The defau
fc50: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
fc60: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
fc70: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c for most.** appl
fc80: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 ications and so
fc90: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
fca0: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 usually not nece
fcb0: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a ssary. It is.**
fcc0: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 provided to sup
fcd0: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 port rare applic
fce0: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 ations with unus
fcf0: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ual needs..**.**
fd00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
fd10: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
fd20: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 is not threadsaf
fd30: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 e. The applicat
fd40: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 ion.** must insu
fd50: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 re that no other
fd60: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
fd70: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 es are invoked b
fd80: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 y other.** threa
fd90: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 ds while sqlite3
fda0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e _config() is run
fdb0: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f ning. Furthermo
fdc0: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 re, sqlite3_conf
fdd0: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ig().** may only
fde0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f be invoked prio
fdf0: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 r to library ini
fe00: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e tialization usin
fe10: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e g.** [sqlite3_in
fe20: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 itialize()] or a
fe30: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 fter shutdown by
fe40: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
fe50: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 wn()]..** ^If sq
fe60: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
fe70: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b s called after [
fe80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
fe90: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 ze()] and before
fea0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 .** [sqlite3_shu
feb0: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 tdown()] then it
fec0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c will return SQL
fed0: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e ITE_MISUSE..** N
fee0: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 ote, however, th
fef0: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 at ^sqlite3_conf
ff00: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c ig() can be call
ff10: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
ff20: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
ff30: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 ion of an applic
ff40: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 ation-defined [s
ff50: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
ff60: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 ]..**.** The fir
ff70: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
ff80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
ff90: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a is an integer.**
ffa0: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 [configuration
ffb0: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 option] that det
ffc0: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 ermines.** what
ffd0: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 property of SQLi
ffe0: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 te is to be conf
fff0: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 igured. Subsequ
10000 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a ent arguments.**
10010 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 vary depending
10020 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 on the [configur
10030 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a ation option].**
10040 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
10050 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 gument..**.** ^W
10060 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 hen a configurat
10070 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ion option is se
10080 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 t, sqlite3_confi
10090 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c g() returns [SQL
100a0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 ITE_OK]..** ^If
100b0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e the option is un
100c0 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 known or SQLite
100d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 is unable to set
100e0 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 the option.** t
100f0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
10100 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a returns a non-z
10110 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
10120 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
10130 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e _config(int, ...
10140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
10150 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 EF: Configure da
10160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
10170 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ns.**.** The sql
10180 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
10190 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
101a0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
101b0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
101c0 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
101d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
101e0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
101f0 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
10200 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
10210 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
10220 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
10230 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
10240 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
10250 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
10260 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
10270 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 gument)..**.** T
10280 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
10290 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 nt to sqlite3_db
102a0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 _config(D,V,...)
102b0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c is the.** [SQL
102c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
102d0 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 KASIDE | configu
102e0 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 ration verb] - a
102f0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a n integer code .
10300 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 ** that indicate
10310 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 s what aspect of
10320 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
10330 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
10340 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a ing configured..
10350 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 ** Subsequent ar
10360 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 guments vary dep
10370 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
10380 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
10390 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ..**.** ^Calls t
103a0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
103b0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c fig() return SQL
103c0 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e ITE_OK if and on
103d0 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c ly if.** the cal
103e0 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 l is considered
103f0 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 successful..*/.i
10400 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f nt sqlite3_db_co
10410 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 nfig(sqlite3*, i
10420 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a nt op, ...);../*
10430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
10440 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
10450 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 Routines.**.** A
10460 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
10470 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 is object define
10480 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
10490 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a between SQLite.*
104a0 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 * and low-level
104b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
104c0 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a n routines..**.*
104d0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
104e0 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e used in only on
104f0 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 e place in the S
10500 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
10510 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
10520 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
10530 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 this object is t
10540 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a he argument to.*
10550 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
10560 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f g()] when the co
10570 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
10580 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 on is.** [SQLITE
10590 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 _CONFIG_MALLOC]
105a0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
105b0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a G_GETMALLOC]. .
105c0 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 ** By creating a
105d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
105e0 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 is object.** and
105f0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
10600 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
10610 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
10620 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e ALLOC]).** durin
10630 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c g configuration,
10640 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
10650 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 can specify an a
10660 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
10670 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
10680 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 subsystem for SQ
10690 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 Lite to use for
106a0 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 all of its.** dy
106b0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 namic memory nee
106c0 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 ds..**.** Note t
106d0 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 hat SQLite comes
106e0 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 with several [b
106f0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
10700 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 llocators].** th
10710 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 at are perfectly
10720 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 adequate for th
10730 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d e overwhelming m
10740 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 ajority of appli
10750 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 cations.** and t
10760 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 hat this object
10770 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 is only useful t
10780 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 o a tiny minorit
10790 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
107a0 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 s.** with specia
107b0 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c lized memory all
107c0 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d ocation requirem
107d0 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 ents. This obje
107e0 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 ct is.** also us
107f0 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
10800 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f g of SQLite in o
10810 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 rder to specify
10820 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
10830 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
10840 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 or that simulate
10850 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d s memory out-of-
10860 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e memory condition
10870 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f s in.** order to
10880 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c verify that SQL
10890 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 ite recovers gra
108a0 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 cefully from suc
108b0 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e h.** conditions.
108c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c .**.** The xMall
108d0 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e oc, xRealloc, an
108e0 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 d xFree methods
108f0 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 must work like t
10900 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 he.** malloc(),
10910 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 realloc() and fr
10920 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 ee() functions f
10930 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 rom the standard
10940 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e C library..** ^
10950 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 SQLite guarantee
10960 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e s that the secon
10970 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
10980 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 xRealloc is alw
10990 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 ays a value retu
109a0 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 rned by a prior
109b0 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 call to xRoundup
109c0 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 ..**.** xSize sh
109d0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 ould return the
109e0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
109f0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
10a00 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 ation.** previou
10a10 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f sly obtained fro
10a20 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 m xMalloc or xRe
10a30 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f alloc. The allo
10a40 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 cated size.** is
10a50 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 always at least
10a60 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 as big as the r
10a70 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 equested size bu
10a80 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e t may be larger.
10a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e .**.** The xRoun
10aa0 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 dup method retur
10ab0 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 ns what would be
10ac0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 the allocated s
10ad0 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f ize of.** a memo
10ae0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 ry allocation gi
10af0 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 ven a particular
10b00 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e requested size.
10b10 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a Most memory.**
10b20 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e allocators roun
10b30 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f d up memory allo
10b40 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 cations at least
10b50 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c to the next mul
10b60 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 tiple.** of 8.
10b70 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 Some allocators
10b80 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 round up to a la
10b90 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 rger multiple or
10ba0 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 to a power of 2
10bb0 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 ..** Every memor
10bc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
10bd0 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 uest coming in t
10be0 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f hrough [sqlite3_
10bf0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 malloc()].** or
10c00 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
10c10 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 ()] first calls
10c20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 xRoundup. If xR
10c30 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 oundup returns 0
10c40 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 , .** that cause
10c50 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 s the correspond
10c60 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ing memory alloc
10c70 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a ation to fail..*
10c80 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d *.** The xInit m
10c90 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 ethod initialize
10ca0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c s the memory all
10cb0 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 ocator. For exa
10cc0 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 mple,.** it migh
10cd0 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 t allocate any r
10ce0 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f equire mutexes o
10cf0 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 r initialize int
10d00 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 ernal data.** st
10d10 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 ructures. The x
10d20 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 Shutdown method
10d30 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 is invoked (indi
10d40 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 rectly) by.** [s
10d50 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10d60 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 )] and should de
10d70 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 allocate any res
10d80 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a ources acquired.
10d90 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 ** by xInit. Th
10da0 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 e pAppData point
10db0 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 er is used as th
10dc0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 e only parameter
10dd0 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 to.** xInit and
10de0 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a xShutdown..**.*
10df0 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 * SQLite holds t
10e00 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 he [SQLITE_MUTEX
10e10 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 _STATIC_MASTER]
10e20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e mutex when it in
10e30 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e vokes.** the xIn
10e40 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 it method, so th
10e50 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e e xInit method n
10e60 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 eed not be threa
10e70 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 dsafe. The.** x
10e80 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 Shutdown method
10e90 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 is only called f
10ea0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 rom [sqlite3_shu
10eb0 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 tdown()] so it d
10ec0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 oes.** not need
10ed0 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 to be threadsafe
10ee0 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c either. For al
10ef0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c l other methods,
10f00 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 SQLite.** holds
10f10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 the [SQLITE_MUT
10f20 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d EX_STATIC_MEM] m
10f30 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 utex as long as
10f40 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 the.** [SQLITE_C
10f50 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
10f60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
10f70 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 ption is turned
10f80 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 on (which.** it
10f90 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 is by default) a
10fa0 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 nd so the method
10fb0 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 s are automatica
10fc0 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a lly serialized..
10fd0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b ** However, if [
10fe0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
10ff0 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 MSTATUS] is disa
11000 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f bled, then the o
11010 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 ther.** methods
11020 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
11030 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 fe or else make
11040 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 their own arrang
11050 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 ements for.** se
11060 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a rialization..**.
11070 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e ** SQLite will n
11080 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 ever invoke xIni
11090 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e t() more than on
110a0 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e ce without an in
110b0 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c tervening.** cal
110c0 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 l to xShutdown()
110d0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
110e0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f uct sqlite3_mem_
110f0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
11100 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 mem_methods;.str
11110 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f uct sqlite3_mem_
11120 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 methods {. void
11130 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 *(*xMalloc)(int
11140 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 ); /* Me
11150 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
11160 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f function */. vo
11170 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 id (*xFree)(void
11180 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 *); /*
11190 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c Free a prior all
111a0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 ocation */. voi
111b0 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 d *(*xRealloc)(v
111c0 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 oid*,int); /* R
111d0 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 esize an allocat
111e0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
111f0 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 Size)(void*);
11200 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 /* Retur
11210 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e n the size of an
11220 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
11230 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 int (*xRoundup)
11240 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 (int);
11250 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 /* Round up requ
11260 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f est size to allo
11270 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 cation size */.
11280 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f int (*xInit)(vo
11290 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
112a0 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 /* Initialize th
112b0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
112c0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 or */. void (*x
112d0 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 Shutdown)(void*)
112e0 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 ; /* Deinit
112f0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 ialize the memor
11300 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 y allocator */.
11310 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b void *pAppData;
11320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
11330 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 /* Argument to x
11340 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 Init() and xShut
11350 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a down() */.};../*
11360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
11370 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 nfiguration Opti
11380 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ons.** KEYWORDS:
11390 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 {configuration
113a0 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 option}.**.** Th
113b0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
113c0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
113d0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
113e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
113f0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
11400 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
11410 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
11420 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
11430 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
11440 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 *.** New configu
11450 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
11460 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
11470 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
11480 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 f SQLite..** Exi
11490 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 sting configurat
114a0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 ion options migh
114b0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 t be discontinue
114c0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 d. Applications
114d0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b .** should check
114e0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 the return code
114f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 from [sqlite3_c
11500 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 onfig()] to make
11510 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 sure that.** th
11520 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 e call worked.
11530 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e The [sqlite3_con
11540 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
11550 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a will return a.*
11560 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f * non-zero [erro
11570 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 r code] if a dis
11580 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 continued or uns
11590 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 upported configu
115a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a ration option.**
115b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a is invoked..**.
115c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c ** <dl>.** [[SQL
115d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
115e0 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 ETHREAD]] <dt>SQ
115f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
11600 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a LETHREAD</dt>.**
11610 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
11620 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
11630 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
11640 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
11650 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
11660 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 mode] to Single
11670 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
11680 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
11690 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
116a0 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 exing and puts S
116b0 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 QLite into a mod
116c0 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f e where it can o
116d0 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 nly be used.** b
116e0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 y a single threa
116f0 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 d. ^If SQLite
11700 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
11710 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
11720 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
11730 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
11740 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
11750 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
11760 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
11770 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b to change the [
11780 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
11790 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 from its default
117a0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e .** value of Sin
117b0 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 gle-thread and s
117c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
117d0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
117e0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 .** [SQLITE_ERR
117f0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 OR] if called wi
11800 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
11810 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
11820 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 D.** configurati
11830 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a on option.</dd>.
11840 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
11850 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
11860 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
11870 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
11880 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
11890 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
118a0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
118b0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 ion. ^This opti
118c0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b on sets the.** [
118d0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
118e0 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e to Multi-thread.
118f0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
11900 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a , it disables.**
11910 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 mutexing on [da
11920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
11930 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
11940 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
11950 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c cts..** The appl
11960 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f ication is respo
11970 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 nsible for seria
11980 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f lizing access to
11990 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
119a0 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b nnections] and [
119b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
119c0 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 nts]. But other
119d0 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 mutexes.** are
119e0 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 enabled so that
119f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 SQLite will be s
11a00 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 afe to use in a
11a10 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a multi-threaded.*
11a20 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 * environment as
11a30 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 long as no two
11a40 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 threads attempt
11a50 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a to use the same.
11a60 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
11a70 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 nection] at the
11a80 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 same time. ^If
11a90 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
11aa0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
11ab0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
11ac0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
11ad0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
11ae0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
11af0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
11b00 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 ossible to set t
11b10 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 he Multi-thread
11b20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
11b30 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
11b40 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
11b50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
11b60 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 RROR] if called
11b70 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 with the.** SQLI
11b80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
11b90 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 HREAD configurat
11ba0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e ion option.</dd>
11bb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
11bc0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
11bd0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
11be0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
11bf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
11c00 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
11c10 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
11c20 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
11c30 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
11c40 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
11c50 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e o Serialized. In
11c60 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
11c70 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 is option enable
11c80 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 s.** all mutexes
11c90 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 including the r
11ca0 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 ecursive.** mute
11cb0 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 xes on [database
11cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
11cd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
11ce0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
11cf0 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 * In this mode (
11d00 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 which is the def
11d10 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 ault when SQLite
11d20 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
11d30 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 h.** [SQLITE_THR
11d40 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 EADSAFE=1]) the
11d50 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
11d60 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 ill itself seria
11d70 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 lize access.** t
11d80 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e o [database conn
11d90 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
11da0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
11db0 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a s] so that the.*
11dc0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 * application is
11dd0 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 free to use the
11de0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
11df0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 connection] or t
11e00 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 he.** same [prep
11e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
11e20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 in different thr
11e30 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
11e40 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 time..** ^If SQ
11e50 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
11e60 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
11e70 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
11e80 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
11e90 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
11ea0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
11eb0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 ** it is not pos
11ec0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 sible to set the
11ed0 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 Serialized [thr
11ee0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 eading mode] and
11ef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
11f00 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 fig()] will retu
11f10 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
11f20 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
11f30 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 the.** SQLITE_C
11f40 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
11f50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
11f60 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
11f70 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
11f80 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 G_MALLOC]] <dt>S
11f90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
11fa0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
11fb0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
11fc0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
11fd0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
11fe0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
11ff0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
12000 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
12010 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
12020 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e re. The argumen
12030 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 t specifies.** a
12040 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c lternative low-l
12050 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f evel memory allo
12060 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 cation routines
12070 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c to be used in pl
12080 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 ace of.** the me
12090 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
120a0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 routines built i
120b0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 nto SQLite.)^ ^S
120c0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 QLite makes.** i
120d0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ts own private c
120e0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 opy of the conte
120f0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 nt of the [sqlit
12100 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 e3_mem_methods]
12110 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 structure.** bef
12120 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ore the [sqlite3
12130 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 _config()] call
12140 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a returns.</dd>.**
12150 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
12160 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 FIG_GETMALLOC]]
12170 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
12180 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e G_GETMALLOC</dt>
12190 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
121a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
121b0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
121c0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
121d0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
121e0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
121f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
12200 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
12210 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
12220 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 thods].** struct
12230 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 ure is filled wi
12240 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 th the currently
12250 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 defined memory
12260 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
12270 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f nes.)^.** This o
12280 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
12290 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 d to overload th
122a0 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 e default memory
122b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
122c0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
122d0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 rapper that simu
122e0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 lations memory a
122f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 llocation failur
12300 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d e or.** tracks m
12310 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 emory usage, for
12320 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a example. </dd>.
12330 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
12340 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
12350 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12360 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 FIG_MEMSTATUS</d
12370 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
12380 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 option takes si
12390 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 ngle argument of
123a0 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 type int, inter
123b0 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 preted as a .**
123c0 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 boolean, which e
123d0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
123e0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f es the collectio
123f0 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f n of memory allo
12400 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 cation .** stati
12410 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 stics. ^(When me
12420 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12430 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 statistics are d
12440 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a isabled, the .**
12450 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 following SQLit
12460 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 e interfaces bec
12470 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f ome non-operatio
12480 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a nal:.** <ul>.*
12490 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
124a0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
124b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
124c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
124d0 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 ater()].** <li
124e0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f > [sqlite3_soft_
124f0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a heap_limit64()].
12500 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
12510 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 e3_status()].**
12520 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 </ul>)^.** ^Me
12530 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12540 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 statistics are e
12550 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c nabled by defaul
12560 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 t unless SQLite
12570 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 is.** compiled w
12580 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 ith [SQLITE_DEFA
12590 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 ULT_MEMSTATUS]=0
125a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d in which case m
125b0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
125c0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
125d0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
125e0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e efault..** </dd>
125f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
12600 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d CONFIG_SCRATCH]]
12610 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
12620 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a IG_SCRATCH</dt>.
12630 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
12640 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
12650 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 static memory b
12660 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 uffer that SQLit
12670 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a e can use for.**
12680 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e scratch memory.
12690 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 There are thre
126a0 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 e arguments: A
126b0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 pointer an 8-byt
126c0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d e.** aligned mem
126d0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 ory buffer from
126e0 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 which the scratc
126f0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 h allocations wi
12700 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 ll be.** drawn,
12710 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
12720 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
12730 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 ion (sz),.** and
12740 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
12750 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 ber of scratch a
12760 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 llocations (N).
12770 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d The sz.** argum
12780 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 ent must be a mu
12790 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a ltiple of 16..**
127a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
127b0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f ent must be a po
127c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 inter to an 8-by
127d0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 te aligned buffe
127e0 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 r.** of at least
127f0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d sz*N bytes of m
12800 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 emory..** ^SQLit
12810 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f e will use no mo
12820 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 re than two scra
12830 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 tch buffers per
12840 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e thread. So.** N
12850 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 should be set t
12860 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 o twice the expe
12870 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d cted maximum num
12880 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a ber of threads..
12890 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 ** ^SQLite will
128a0 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 never require a
128b0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 scratch buffer t
128c0 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e hat is more than
128d0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 6.** times the
128e0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 database page si
128f0 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e ze. ^If SQLite n
12900 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 eeds needs addit
12910 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 ional.** scratch
12920 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 memory beyond w
12930 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
12940 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 by this configur
12950 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 ation option, th
12960 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f en .** [sqlite3_
12970 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 malloc()] will b
12980 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
12990 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 the memory need
129a0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ed.</dd>.**.** [
129b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
129c0 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 AGECACHE]] <dt>S
129d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
129e0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c ECACHE</dt>.** <
129f0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
12a00 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
12a10 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
12a20 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 r that SQLite ca
12a30 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 n use for.** the
12a40 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 database page c
12a50 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 ache with the de
12a60 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 fault page cache
12a70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
12a80 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 .** This confi
12a90 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 guration should
12aa0 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 not be used if a
12ab0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
12ac0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 fine page.** cac
12ad0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
12ae0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e n is loaded usin
12af0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e g the SQLITE_CON
12b00 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 FIG_PCACHE2 opti
12b10 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 on..** There are
12b20 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 three arguments
12b30 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a to this option:
12b40 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d A pointer to 8-
12b50 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 byte aligned.**
12b60 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 memory, the size
12b70 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 of each page bu
12b80 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 ffer (sz), and t
12b90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 he number of pag
12ba0 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 es (N)..** The s
12bb0 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c z argument shoul
12bc0 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 d be the size of
12bd0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 the largest dat
12be0 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 abase page.** (a
12bf0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 power of two be
12c00 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 tween 512 and 32
12c10 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 768) plus a litt
12c20 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 le extra for eac
12c30 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 h.** page header
12c40 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 . ^The page hea
12c50 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 der size is 20 t
12c60 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e o 40 bytes depen
12c70 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 ding on.** the h
12c80 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 ost architecture
12c90 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 . ^It is harmle
12ca0 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 ss, apart from t
12cb0 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 he wasted memory
12cc0 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 ,.** to make sz
12cd0 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 a little too lar
12ce0 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a ge. The first.*
12cf0 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c * argument shoul
12d00 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c d point to an al
12d10 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c location of at l
12d20 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 east sz*N bytes
12d30 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 of memory..** ^S
12d40 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 QLite will use t
12d50 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 he memory provid
12d60 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
12d70 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 argument to sati
12d80 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 sfy its.** memor
12d90 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 y needs for the
12da0 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 first N pages th
12db0 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 at it adds to ca
12dc0 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 che. ^If additi
12dd0 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 onal.** page cac
12de0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 he memory is nee
12df0 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 ded beyond what
12e00 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 is provided by t
12e10 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e his option, then
12e20 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 .** SQLite goes
12e30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
12e40 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 oc()] for the ad
12e50 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 ditional storage
12e60 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 space..** The p
12e70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 ointer in the fi
12e80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
12e90 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 t.** be aligned
12ea0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 to an 8-byte bou
12eb0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 ndary or subsequ
12ec0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 ent behavior of
12ed0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 SQLite.** will b
12ee0 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 e undefined.</dd
12ef0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
12f00 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c _CONFIG_HEAP]] <
12f10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
12f20 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _HEAP</dt>.** <d
12f30 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
12f40 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
12f50 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
12f60 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
12f70 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c l use.** for all
12f80 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 of its dynamic
12f90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12fa0 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 n needs beyond t
12fb0 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a hose provided.**
12fc0 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f for by [SQLITE_
12fd0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 CONFIG_SCRATCH]
12fe0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 and [SQLITE_CONF
12ff0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
13000 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 * There are thre
13010 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 e arguments: An
13020 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 8-byte aligned p
13030 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
13040 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d mory,.** the num
13050 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
13060 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 the memory buffe
13070 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d r, and the minim
13080 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
13090 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 ze..** ^If the f
130a0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 irst pointer (th
130b0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 e memory pointer
130c0 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 ) is NULL, then
130d0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a SQLite reverts.*
130e0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 * to using its d
130f0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c efault memory al
13100 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 locator (the sys
13110 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 tem malloc() imp
13120 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a lementation),.**
13130 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 undoing any pri
13140 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 or invocation of
13150 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
13160 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 MALLOC]. ^If th
13170 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e e.** memory poin
13180 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 ter is not NULL
13190 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 and either [SQLI
131a0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 TE_ENABLE_MEMSYS
131b0 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 3] or.** [SQLITE
131c0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d _ENABLE_MEMSYS5]
131d0 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 are defined, th
131e0 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 en the alternati
131f0 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c ve memory.** all
13200 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 ocator is engage
13210 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 d to handle all
13220 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 of SQLites memor
13230 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
13240 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ds..** The first
13250 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 pointer (the me
13260 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 mory pointer) mu
13270 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f st be aligned to
13280 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f an 8-byte.** bo
13290 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 undary or subseq
132a0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 uent behavior of
132b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 SQLite will be
132c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 undefined..** Th
132d0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
132e0 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 tion size is cap
132f0 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 ped at 2**12. Re
13300 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a asonable values.
13310 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d ** for the minim
13320 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
13330 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f ze are 2**5 thro
13340 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a ugh 2**8.</dd>.*
13350 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
13360 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 NFIG_MUTEX]] <dt
13370 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
13380 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
13390 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
133a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
133b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
133c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
133d0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
133e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
133f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
13400 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 cture. The argu
13410 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a ment specifies.*
13420 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f * alternative lo
13430 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f w-level mutex ro
13440 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
13450 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 d in place.** th
13460 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 e mutex routines
13470 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
13480 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d te.)^ ^SQLite m
13490 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
134a0 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 he.** content of
134b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
134c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
134d0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 ucture before th
134e0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 e call to.** [sq
134f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
13500 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c returns. ^If SQL
13510 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
13520 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
13530 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
13540 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
13550 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
13560 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
13570 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 * the entire mut
13580 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 exing subsystem
13590 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
135a0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 the build and he
135b0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 nce calls to.**
135c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
135d0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 )] with the SQLI
135e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 TE_CONFIG_MUTEX
135f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
13600 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 tion will.** ret
13610 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
13620 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b R].</dd>.**.** [
13630 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
13640 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 ETMUTEX]] <dt>SQ
13650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
13660 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
13670 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
13680 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
13690 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
136a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
136b0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
136c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
136d0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
136e0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b cture. The.** [
136f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
13700 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 thods].** struct
13710 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 ure is filled wi
13720 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 th the currently
13730 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 defined mutex r
13740 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 outines.)^.** Th
13750 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 is option can be
13760 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 used to overloa
13770 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 d the default mu
13780 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a tex allocation.*
13790 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 * routines with
137a0 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 a wrapper used t
137b0 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 o track mutex us
137c0 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 age for performa
137d0 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 nce.** profiling
137e0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 or testing, for
137f0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 example. ^If
13800 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
13810 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
13820 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
13830 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
13840 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
13850 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
13860 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 n.** the entire
13870 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 mutexing subsyst
13880 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 em is omitted fr
13890 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 om the build and
138a0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a hence calls to.
138b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
138c0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 ig()] with the S
138d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
138e0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 MUTEX configurat
138f0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a ion option will.
13900 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ** return [SQLIT
13910 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a E_ERROR].</dd>.*
13920 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
13930 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d NFIG_LOOKASIDE]]
13940 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
13950 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 IG_LOOKASIDE</dt
13960 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
13970 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 option takes tw
13980 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 o arguments that
13990 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 determine the d
139a0 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 efault.** memory
139b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 allocation for
139c0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 the lookaside me
139d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f mory allocator o
139e0 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 n each.** [datab
139f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
13a00 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 The first argu
13a10 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
13a20 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
13a30 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
13a40 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 t and the second
13a50 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
13a60 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 f.** slots alloc
13a70 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 ated to each dat
13a80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13a90 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 .)^ ^(This opti
13aa0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c on sets the.** <
13ab0 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f i>default</i> lo
13ac0 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 okaside size. Th
13ad0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 e [SQLITE_DBCONF
13ae0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a IG_LOOKASIDE].**
13af0 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 verb to [sqlite
13b00 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 3_db_config()] c
13b10 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 an be used to ch
13b20 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 ange the lookasi
13b30 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 de.** configurat
13b40 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 ion on individua
13b50 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e l connections.)^
13b60 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
13b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
13b80 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 CHE2]] <dt>SQLIT
13b90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 E_CONFIG_PCACHE2
13ba0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
13bb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
13bc0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
13bd0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
13be0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 ointer to.** an
13bf0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
13c00 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
13c10 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 . This object s
13c20 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 pecifies the int
13c30 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 erface.** to a c
13c40 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 ustom page cache
13c50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
13c60 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 )^ ^SQLite make
13c70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
13c80 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 ** object and us
13c90 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 es it for page c
13ca0 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ache memory allo
13cb0 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a cations.</dd>.**
13cc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
13cd0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d FIG_GETPCACHE2]]
13ce0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
13cf0 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 IG_GETPCACHE2</d
13d00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 t>.** <dd> ^(Thi
13d10 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
13d20 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
13d30 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
13d40 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 ter to an.** [sq
13d50 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
13d60 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 hods2] object.
13d70 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 SQLite copies of
13d80 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
13d90 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
13da0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 mentation into t
13db0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f hat object.)^ </
13dc0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
13dd0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 TE_CONFIG_LOG]]
13de0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
13df0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 G_LOG</dt>.** <d
13e00 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d> The SQLITE_CO
13e10 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 NFIG_LOG option
13e20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 is used to confi
13e30 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a gure the SQLite.
13e40 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 ** global [error
13e50 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 log]..** (^The
13e60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
13e70 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 G option takes t
13e80 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 wo arguments: a
13e90 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 pointer to a.**
13ea0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
13eb0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f call signature o
13ec0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c f void(*)(void*,
13ed0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 int,const char*)
13ee0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e , .** and a poin
13ef0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 ter to void. ^If
13f00 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f the function po
13f10 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c inter is not NUL
13f20 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f L, it is.** invo
13f30 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ked by [sqlite3_
13f40 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 log()] to proces
13f50 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 s each logging e
13f60 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
13f70 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 * function point
13f80 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 er is NULL, the
13f90 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 [sqlite3_log()]
13fa0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 interface become
13fb0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 s a no-op..** ^T
13fc0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 he void pointer
13fd0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f that is the seco
13fe0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 nd argument to S
13ff0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
14000 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 is.** passed th
14010 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 rough as the fir
14020 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
14030 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
14040 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a defined logger.*
14050 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 * function whene
14060 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f ver that functio
14070 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e n is invoked. ^
14080 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
14090 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c eter to.** the l
140a0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 ogger function i
140b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
140c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
140d0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e to the correspon
140e0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ding.** [sqlite3
140f0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 _log()] call and
14100 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
14110 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 be a [result cod
14120 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 e] or an.** [ext
14130 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
14140 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 e]. ^The third
14150 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 parameter passed
14160 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 to the logger i
14170 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 s.** log message
14180 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e after formattin
14190 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 g via [sqlite3_s
141a0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 nprintf()]..** T
141b0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e he SQLite loggin
141c0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e g interface is n
141d0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 ot reentrant; th
141e0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
141f0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 n.** supplied by
14200 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
14210 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 must not invoke
14220 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 any SQLite inte
14230 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d rface..** In a m
14240 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 ulti-threaded ap
14250 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 plication, the a
14260 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
14270 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e ed logger.** fun
14280 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 ction must be th
14290 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a readsafe. </dd>.
142a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
142b0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e ONFIG_URI]] <dt>
142c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
142d0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20 I.** <dd>^(This
142e0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
142f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f ingle argument o
14300 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e f type int. If n
14310 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a on-zero, then.**
14320 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 URI handling is
14330 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 globally enable
14340 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 d. If the parame
14350 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 ter is zero, the
14360 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a n URI handling.*
14370 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 * is globally di
14380 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 sabled.)^ ^If UR
14390 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
143a0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 obally enabled,
143b0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a all filenames.**
143c0 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 passed to [sqli
143d0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
143e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
143f0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
14400 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 6()] or.** speci
14410 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 fied as part of
14420 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 [ATTACH] command
14430 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 s are interprete
14440 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 d as URIs, regar
14450 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 dless.** of whet
14460 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b her or not the [
14470 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
14480 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 flag is set whe
14490 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a n the database.*
144a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 * connection is
144b0 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 opened. ^If it i
144c0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 s globally disab
144d0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 led, filenames a
144e0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 re.** only inter
144f0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 preted as URIs i
14500 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 f the SQLITE_OPE
14510 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 N_URI flag is se
14520 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 t when the.** da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14540 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 n is opened. ^(B
14550 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 y default, URI h
14560 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
14570 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e lly.** disabled.
14580 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c The default val
14590 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 ue may be change
145a0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 d by compiling w
145b0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
145c0 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 TE_USE_URI] symb
145d0 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a ol defined.)^.**
145e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
145f0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
14600 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 EX_SCAN]] <dt>SQ
14610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
14620 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a RING_INDEX_SCAN.
14630 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 ** <dd>^This opt
14640 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
14650 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d le integer argum
14660 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 ent which is int
14670 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 erpreted as.** a
14680 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 boolean in orde
14690 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 r to enable or d
146a0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f isable the use o
146b0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 f covering indic
146c0 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 es for.** full t
146d0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 able scans in th
146e0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 e query optimize
146f0 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 r. ^The default
14700 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 setting is dete
14710 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 rmined.** by the
14720 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 [SQLITE_ALLOW_C
14730 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 OVERING_INDEX_SC
14740 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 AN] compile-time
14750 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 option, or is "
14760 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 on".** if that c
14770 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
14780 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a on is omitted..*
14790 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f * The ability to
147a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 disable the use
147b0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 of covering ind
147c0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 ices for full ta
147d0 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 ble scans.** is
147e0 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 because some inc
147f0 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c orrectly coded l
14800 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f egacy applicatio
14810 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 ns might malfunc
14820 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 tion.** when the
14830 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 optimization is
14840 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 enabled. Provi
14850 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 ding the ability
14860 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 to.** disable t
14870 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 he optimization
14880 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 allows the older
14890 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 , buggy applicat
148a0 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b ion code to work
148b0 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e .** without chan
148c0 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 ge even with new
148d0 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 er versions of S
148e0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 QLite..**.** [[S
148f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
14900 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 CHE]] [[SQLITE_C
14910 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d ONFIG_GETPCACHE]
14920 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
14930 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e CONFIG_PCACHE an
14940 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f d SQLITE_CONFIG_
14950 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 GETPCACHE.** <dd
14960 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 > These options
14970 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 are obsolete and
14980 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 should not be u
14990 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e sed by new code.
149a0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 .** They are ret
149b0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 ained for backwa
149c0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
149d0 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f y but are now no
149e0 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a -ops..** </dd>.*
149f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
14a00 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a NFIG_SQLLOG]].**
14a10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
14a20 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 IG_SQLLOG.** <dd
14a30 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 >This option is
14a40 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 only available i
14a50 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 f sqlite is comp
14a60 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a iled with the.**
14a70 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
14a80 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 SQLLOG] pre-proc
14a90 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 essor macro defi
14aa0 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 ned. The first a
14ab0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a rgument should.*
14ac0 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 * be a pointer t
14ad0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 o a function of
14ae0 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 type void(*)(voi
14af0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 d*,sqlite3*,cons
14b00 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a t char*, int)..*
14b10 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f * The second sho
14b20 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 uld be of type (
14b30 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c void*). The call
14b40 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
14b50 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a by the library.*
14b60 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 * in three separ
14b70 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 ate circumstance
14b80 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 s, identified by
14b90 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 the value passe
14ba0 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 d as the.** four
14bb0 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 th parameter. If
14bc0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
14bd0 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e meter is 0, then
14be0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
14bf0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 nnection.** pass
14c00 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
14c10 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 argument has ju
14c20 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 st been opened.
14c30 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
14c40 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 nt.** points to
14c50 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e a buffer contain
14c60 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 ing the name of
14c70 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 the main databas
14c80 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a e file. If the.*
14c90 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 * fourth paramet
14ca0 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 er is 1, then th
14cb0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
14cc0 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 that the third p
14cd0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e arameter.** poin
14ce0 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 ts to has just b
14cf0 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 een executed. Or
14d00 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 , if the fourth
14d10 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 parameter is 2,
14d20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e then.** the conn
14d30 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 ection being pas
14d40 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
14d50 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 d parameter is b
14d60 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 eing closed. The
14d70 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 .** third parame
14d80 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 ter is passed NU
14d90 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e LL In this case.
14da0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 An example of
14db0 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f using this.** co
14dc0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
14dd0 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 on can be seen i
14de0 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c n the "test_sqll
14df0 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c og.c" source fil
14e00 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f e in.** the cano
14e10 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 nical SQLite sou
14e20 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a rce tree.</dd>.*
14e30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
14e40 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d NFIG_MMAP_SIZE]]
14e50 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
14e60 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a ONFIG_MMAP_SIZE.
14e70 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 ** <dd>^SQLITE_C
14e80 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 ONFIG_MMAP_SIZE
14e90 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 takes two 64-bit
14ea0 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 integer (sqlite
14eb0 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 3_int64) values.
14ec0 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 ** that are the
14ed0 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a default mmap siz
14ee0 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 e limit (the def
14ef0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 ault setting for
14f00 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 .** [PRAGMA mmap
14f10 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 _size]) and the
14f20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 maximum allowed
14f30 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e mmap size limit.
14f40 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 .** ^The default
14f50 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 setting can be
14f60 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 overridden by ea
14f70 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ch database conn
14f80 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 ection using.**
14f90 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 either the [PRAG
14fa0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f MA mmap_size] co
14fb0 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 mmand, or by usi
14fc0 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 ng the.** [SQLIT
14fd0 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a E_FCNTL_MMAP_SIZ
14fe0 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e E] file control.
14ff0 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 ^(The maximum
15000 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a allowed mmap siz
15010 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63 e.** cannot be c
15020 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69 hanged at run-ti
15030 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65 me. Nor may the
15040 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 maximum allowed
15050 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78 mmap size.** ex
15060 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 ceed the compile
15070 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d -time maximum mm
15080 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 ap size set by t
15090 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 he.** [SQLITE_MA
150a0 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d X_MMAP_SIZE] com
150b0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
150c0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 .)^.** ^If eithe
150d0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 r argument to th
150e0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 is option is neg
150f0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 ative, then that
15100 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
15110 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 changed to its c
15120 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 ompile-time defa
15130 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ult..**.** [[SQL
15140 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
15150 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c _HEAPSIZE]].** <
15160 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15170 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a _WIN32_HEAPSIZE.
15180 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 ** <dd>^This opt
15190 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
151a0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 lable if SQLite
151b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 is compiled for
151c0 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68 20 Windows.** with
151d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 the [SQLITE_WIN3
151e0 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 2_MALLOC] pre-pr
151f0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 ocessor macro de
15200 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54 45 fined..** SQLITE
15210 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
15220 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 APSIZE takes a 3
15230 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 2-bit unsigned i
15240 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 nteger value.**
15250 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 that specifies t
15260 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 he maximum size
15270 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 of the created h
15280 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f eap..** </dl>.*/
15290 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
152a0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
152b0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a EAD 1 /* nil *
152c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
152d0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
152e0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 EAD 2 /* nil
152f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15300 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
15310 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c ZED 3 /* nil
15320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15330 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
15340 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 4 /* sq
15350 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
15360 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
15370 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
15380 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 ALLOC 5 /*
15390 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
153a0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
153b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
153c0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f RATCH 6 /
153d0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c * void*, int sz,
153e0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e int N */.#defin
153f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15400 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 PAGECACHE 7
15410 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
15420 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
15430 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
15440 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 G_HEAP
15450 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 8 /* void*, int
15460 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 nByte, int min
15470 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15480 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
15490 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f US 9 /* boo
154a0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 lean */.#define
154b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
154c0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f TEX 10 /
154d0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
154e0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
154f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
15500 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 G_GETMUTEX 1
15510 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 1 /* sqlite3_mu
15520 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a tex_methods* */.
15530 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 /* previously SQ
15540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e LITE_CONFIG_CHUN
15550 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 KALLOC 12 which
15560 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a is now unused. *
15570 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 / .#define SQLIT
15580 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
15590 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 DE 13 /* int
155a0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
155b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
155c0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f ACHE 14 /
155d0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 * no-op */.#defi
155e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
155f0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 _GETPCACHE 15
15600 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 /* no-op */.#d
15610 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
15620 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 FIG_LOG
15630 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 16 /* xFunc, v
15640 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
15650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
15660 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f I 17 /
15670 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 * int */.#define
15680 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
15690 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 CACHE2 18
156a0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
156b0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 e_methods2* */.#
156c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
156d0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 NFIG_GETPCACHE2
156e0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 19 /* sqlite3
156f0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
15700 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
15710 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
15720 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 ING_INDEX_SCAN 2
15730 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 0 /* int */.#de
15740 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
15750 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 IG_SQLLOG
15760 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 21 /* xSqllog,
15770 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
15780 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
15790 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 MAP_SIZE 22
157a0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 /* sqlite3_int64
157b0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
157c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
157d0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
157e0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 EAPSIZE 23
157f0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f /* int nByte */
15800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
15810 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
15820 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 ction Configurat
15830 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a ion Options.**.*
15840 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
15850 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 s are the availa
15860 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 ble integer conf
15870 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
15880 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 s that.** can be
15890 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
158a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
158b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 o the [sqlite3_d
158c0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 b_config()] inte
158d0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
158e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
158f0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
15900 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
15910 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
15920 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
15930 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
15940 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
15950 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
15960 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
15970 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
15980 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
15990 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
159a0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ()] to make sure
159b0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c that.** the cal
159c0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 l worked. ^The
159d0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
159e0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ig()] interface
159f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a will return a.**
15a00 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 non-zero [error
15a10 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 code] if a disc
15a20 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 ontinued or unsu
15a30 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 pported configur
15a40 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 ation option.**
15a50 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
15a60 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 * <dl>.** <dt>SQ
15a70 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
15a80 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 OKASIDE</dt>.**
15a90 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
15aa0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 n takes three ad
15ab0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
15ac0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e ts that determin
15ad0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 e the .** [looka
15ae0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f side memory allo
15af0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 cator] configura
15b00 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 tion for the [da
15b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
15b20 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 n]..** ^The firs
15b30 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 t argument (the
15b40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
15b50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 to [sqlite3_db_c
15b60 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a onfig()] is a.**
15b70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 pointer to a me
15b80 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 mory buffer to u
15b90 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 se for lookaside
15ba0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 memory..** ^The
15bb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
15bc0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 after the SQLITE
15bd0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
15be0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 IDE verb.** may
15bf0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 be NULL in which
15c00 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c case SQLite wil
15c10 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a l allocate the.*
15c20 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 * lookaside buff
15c30 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 er itself using
15c40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
15c50 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 )]. ^The second
15c60 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a argument is the.
15c70 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 ** size of each
15c80 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
15c90 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 slot. ^The thi
15ca0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 rd argument is t
15cb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
15cc0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 slots. The size
15cd0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 of the buffer i
15ce0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
15cf0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 ment must be gre
15d00 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 ater than.** or
15d10 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f equal to the pro
15d20 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f duct of the seco
15d30 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 nd and third arg
15d40 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 uments. The buf
15d50 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 fer.** must be a
15d60 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 ligned to an 8-b
15d70 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e yte boundary. ^
15d80 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 If the second ar
15d90 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c gument to.** SQL
15da0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
15db0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 KASIDE is not a
15dc0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 multiple of 8, i
15dd0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a t is internally.
15de0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 ** rounded down
15df0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c to the next smal
15e00 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 ler multiple of
15e10 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 8. ^(The lookas
15e20 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f ide memory.** co
15e30 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 nfiguration for
15e40 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
15e50 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 ction can only b
15e60 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 e changed when t
15e70 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f hat.** connectio
15e80 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 n is not current
15e90 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 ly using lookasi
15ea0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e de memory, or in
15eb0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 other words.**
15ec0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e when the "curren
15ed0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 t value" returne
15ee0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
15ef0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 _db_status](D,[S
15f00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
15f10 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 KASIDE],...) is
15f20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 zero..** Any att
15f30 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 empt to change t
15f40 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d he lookaside mem
15f50 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ory configuratio
15f60 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 n when lookaside
15f70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e .** memory is in
15f80 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 use leaves the
15f90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e configuration un
15fa0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 changed and retu
15fb0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f rns .** [SQLITE_
15fc0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a BUSY].)^</dd>.**
15fd0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
15fe0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 BCONFIG_ENABLE_F
15ff0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e KEY</dt>.** <dd>
16000 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 ^This option is
16010 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 used to enable
16020 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 or disable the e
16030 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a nforcement of.**
16040 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f [foreign key co
16050 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 nstraints]. The
16060 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f re should be two
16070 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
16080 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 ments..** The fi
16090 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
160a0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
160b0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
160c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c FK enforcement,
160d0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 .** positive to
160e0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 enable FK enforc
160f0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 ement or negativ
16100 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e e to leave FK en
16110 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 forcement.** unc
16120 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 hanged. The sec
16130 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
16140 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
16150 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 integer into wh
16160 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 ich.** is writte
16170 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 n 0 or 1 to indi
16180 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 cate whether FK
16190 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f enforcement is o
161a0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c ff or on.** foll
161b0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e owing this call.
161c0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 The second par
161d0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 ameter may be a
161e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e NULL pointer, in
161f0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 .** which case t
16200 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e he FK enforcemen
16210 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 t setting is not
16220 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 reported back.
16230 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
16240 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
16250 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f ENABLE_TRIGGER</
16260 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
16270 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 s option is used
16280 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 to enable or di
16290 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 sable [CREATE TR
162a0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 IGGER | triggers
162b0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 ]..** There shou
162c0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 ld be two additi
162d0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a onal arguments..
162e0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
162f0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 ument is an inte
16300 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 ger which is 0 t
16310 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 o disable trigge
16320 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 rs,.** positive
16330 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 to enable trigge
16340 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 rs or negative t
16350 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 o leave the sett
16360 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a ing unchanged..*
16370 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * The second par
16380 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
16390 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
163a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 r into which.**
163b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
163c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
163d0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 ether triggers a
163e0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 re disabled or e
163f0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 nabled.** follow
16400 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 ing this call.
16410 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
16420 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 eter may be a NU
16430 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a LL pointer, in.*
16440 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 * which case the
16450 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 trigger setting
16460 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 is not reported
16470 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a back. </dd>.**.
16480 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
16490 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
164a0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 FIG_LOOKASIDE
164b0 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 1001 /* voi
164c0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 d* int int */.#d
164d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
164e0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 ONFIG_ENABLE_FKE
164f0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 Y 1002 /* i
16500 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
16510 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
16520 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
16530 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 R 1003 /* int
16540 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 int* */.../*.**
16550 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
16560 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 Or Disable Exte
16570 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 nded Result Code
16580 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
16590 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
165a0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 sult_codes() rou
165b0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 tine enables or
165c0 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 disables the.**
165d0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
165e0 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 codes] feature
165f0 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 of SQLite. ^The
16600 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a extended result.
16610 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 ** codes are dis
16620 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
16630 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 for historical
16640 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
16650 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 /.int sqlite3_ex
16660 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
16670 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e des(sqlite3*, in
16680 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
16690 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 CAPI3REF: Last
166a0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a Insert Rowid.**.
166b0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 ** ^Each entry i
166c0 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 n most SQLite ta
166d0 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 bles (except for
166e0 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d [WITHOUT ROWID]
166f0 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 tables).** has
16700 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 a unique 64-bit
16710 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 signed.** intege
16720 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 r key called the
16730 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 [ROWID | "rowid
16740 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 "]. ^The rowid i
16750 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 s always availab
16760 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 le.** as an unde
16770 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 clared column na
16780 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 med ROWID, OID,
16790 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f or _ROWID_ as lo
167a0 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e ng as those.** n
167b0 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 ames are not als
167c0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 o used by explic
167d0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f itly declared co
167e0 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 lumns. ^If.** th
167f0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f e table has a co
16800 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e lumn of type [IN
16810 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 TEGER PRIMARY KE
16820 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c Y] then that col
16830 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 umn.** is anothe
16840 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 r alias for the
16850 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rowid..**.** ^Th
16860 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 e sqlite3_last_i
16870 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 nsert_rowid(D) i
16880 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
16890 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
168a0 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 the .** most rec
168b0 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b ent successful [
168c0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 INSERT] into a r
168d0 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 owid table or [v
168e0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a irtual table].**
168f0 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e on database con
16900 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 nection D..** ^I
16910 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 nserts into [WIT
16920 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c HOUT ROWID] tabl
16930 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 es are not recor
16940 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 ded..** ^If no s
16950 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
16960 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 T]s into rowid t
16970 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 ables.** have ev
16980 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 er occurred on t
16990 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
169a0 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 ection D, .** th
169b0 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f en sqlite3_last_
169c0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 insert_rowid(D)
169d0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
169e0 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 .** ^(If an [INS
169f0 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 ERT] occurs with
16a00 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 in a trigger or
16a10 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 within a [virtua
16a20 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 l table].** meth
16a30 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f od, then this ro
16a40 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 utine will retur
16a50 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 n the [rowid] of
16a60 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a the inserted.**
16a70 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 row as long as
16a80 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 the trigger or v
16a90 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 irtual table met
16aa0 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a hod is running..
16ab0 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 ** But once the
16ac0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 trigger or virtu
16ad0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 al table method
16ae0 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 ends, the value
16af0 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 returned .** by
16b00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 this routine rev
16b10 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 erts to what it
16b20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 was before the t
16b30 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 rigger or virtua
16b40 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f l.** table metho
16b50 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a d began.)^.**.**
16b60 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 ^An [INSERT] th
16b70 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 at fails due to
16b80 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
16b90 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a lation is not a.
16ba0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 ** successful [I
16bb0 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 NSERT] and does
16bc0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
16bd0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
16be0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
16bf0 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 . ^Thus INSERT
16c00 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 OR FAIL, INSERT
16c10 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 OR IGNORE, INSER
16c20 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a T OR ROLLBACK,.*
16c30 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 * and INSERT OR
16c40 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 ABORT make no ch
16c50 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 anges to the ret
16c60 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
16c70 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 s.** routine whe
16c80 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f n their insertio
16c90 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e n fails. ^(When
16ca0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 INSERT OR REPLA
16cb0 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 CE.** encounters
16cc0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 a constraint vi
16cd0 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 olation, it does
16ce0 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a not fail. The.
16cf0 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e ** INSERT contin
16d00 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f ues to completio
16d10 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 n after deleting
16d20 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 rows that cause
16d30 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 d.** the constra
16d40 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 int problem so I
16d50 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 NSERT OR REPLACE
16d60 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 will always cha
16d70 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 nge.** the retur
16d80 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
16d90 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a interface.)^.**.
16da0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 ** ^For the purp
16db0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 oses of this rou
16dc0 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 tine, an [INSERT
16dd0 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 ] is considered
16de0 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 to.** be success
16df0 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 ful even if it i
16e00 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 s subsequently r
16e10 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a olled back..**.*
16e20 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
16e30 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f is accessible to
16e40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
16e50 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 via the.** [last
16e60 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 _insert_rowid()
16e70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a SQL function]..*
16e80 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
16e90 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 te thread perfor
16ea0 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 ms a new [INSERT
16eb0 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a ] on the same.**
16ec0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
16ed0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b tion while the [
16ee0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
16ef0 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 ert_rowid()].**
16f00 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
16f10 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 ing and thus cha
16f20 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e nges the last in
16f30 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a sert [rowid],.**
16f40 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 then the value
16f50 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
16f60 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
16f70 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 _rowid()] is.**
16f80 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
16f90 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 d might not equa
16fa0 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 l either the old
16fb0 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c or the new.** l
16fc0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 ast insert [rowi
16fd0 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 d]..*/.sqlite3_i
16fe0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 nt64 sqlite3_las
16ff0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 t_insert_rowid(s
17000 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
17010 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 CAPI3REF: Count
17020 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 The Number Of R
17030 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a ows Modified.**.
17040 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
17050 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
17060 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 mber of database
17070 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 rows that were
17080 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e changed.** or in
17090 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
170a0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 d by the most re
170b0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 cently completed
170c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a SQL statement.*
170d0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 * on the [databa
170e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
170f0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
17100 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
17110 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 .** ^(Only chang
17120 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 es that are dire
17130 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 ctly specified b
17140 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 y the [INSERT],
17150 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 [UPDATE],.** or
17160 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 [DELETE] stateme
17170 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 nt are counted.
17180 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 Auxiliary chang
17190 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 es caused by.**
171a0 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 triggers or [for
171b0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 eign key actions
171c0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 ] are not counte
171d0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 d.)^ Use the.**
171e0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
171f0 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 hanges()] functi
17200 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 on to find the t
17210 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 otal number of c
17220 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 hanges.** includ
17230 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 ing changes caus
17240 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 ed by triggers a
17250 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 nd foreign key a
17260 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 ctions..**.** ^C
17270 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 hanges to a view
17280 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 that are simula
17290 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 ted by an [INSTE
172a0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a AD OF trigger].*
172b0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 * are not counte
172c0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 d. Only real ta
172d0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 ble changes are
172e0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e counted..**.** ^
172f0 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 (A "row change"
17300 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 is a change to a
17310 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 single row of a
17320 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a single table.**
17330 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e caused by an IN
17340 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 SERT, DELETE, or
17350 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e UPDATE statemen
17360 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a t. Rows that.**
17370 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 are changed as
17380 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 side effects of
17390 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 [REPLACE] constr
173a0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c aint resolution,
173b0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 .** rollback, AB
173c0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 ORT processing,
173d0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 [DROP TABLE], or
173e0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a by any other.**
173f0 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e mechanisms do n
17400 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 ot count as dire
17410 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 ct row changes.)
17420 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 ^.**.** A "trigg
17430 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 er context" is a
17440 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 scope of execut
17450 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 ion that begins
17460 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 and.** ends with
17470 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 the script of a
17480 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
17490 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a | trigger]. .**
174a0 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d Most SQL statem
174b0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c ents are.** eval
174c0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 uated outside of
174d0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 any trigger. T
174e0 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 his is the "top
174f0 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 level".** trigge
17500 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 r context. If a
17510 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 trigger fires f
17520 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 rom the top leve
17530 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 l, a.** new trig
17540 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 ger context is e
17550 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 ntered for the d
17560 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 uration of that
17570 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 one.** trigger.
17580 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 Subtriggers cre
17590 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 ate subcontexts
175a0 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 for their durati
175b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 on..**.** ^Calli
175c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ng [sqlite3_exec
175d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
175e0 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 step()] recursiv
175f0 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 ely does.** not
17600 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 create a new tri
17610 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a gger context..**
17620 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
17630 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
17640 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 umber of direct
17650 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 row changes in t
17660 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e he.** most recen
17670 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 t INSERT, UPDATE
17680 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 , or DELETE stat
17690 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 ement within the
176a0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 same.** trigger
176b0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
176c0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c ^Thus, when call
176d0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 ed from the top
176e0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 level, this func
176f0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
17700 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 .** number of ch
17710 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 anges in the mos
17720 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c t recent INSERT,
17730 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
17740 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 TE.** that also
17750 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 occurred at the
17760 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 top level. ^(Wi
17770 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
17780 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 a trigger,.** t
17790 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 he sqlite3_chang
177a0 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 es() interface c
177b0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 an be called to
177c0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
177d0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e of.** changes in
177e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
177f0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
17800 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
17810 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d DELETE.** statem
17820 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 ent within the b
17830 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ody of the same
17840 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 trigger..** Howe
17850 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 ver, the number
17860 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f returned does no
17870 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 t include change
17880 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 s.** caused by s
17890 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 ubtriggers since
178a0 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 those have thei
178b0 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e r own context.)^
178c0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
178d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 the [sqlite3_tot
178e0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e al_changes()] in
178f0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 terface, the.**
17900 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 [count_changes p
17910 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 ragma], and the
17920 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 [changes() SQL f
17930 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
17940 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
17950 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
17960 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
17970 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
17980 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
17990 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
179a0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
179b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
179c0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 ed.** is unpredi
179d0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
179e0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e eaningful..*/.in
179f0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 t sqlite3_change
17a00 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a s(sqlite3*);../*
17a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f .** CAPI3REF: To
17a20 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f tal Number Of Ro
17a30 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a ws Modified.**.*
17a40 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
17a50 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
17a60 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 ber of row chang
17a70 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e es caused by [IN
17a80 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 SERT],.** [UPDAT
17a90 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 E] or [DELETE] s
17aa0 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 tatements since
17ab0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
17ac0 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 nnection] was op
17ad0 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 ened..** ^(The c
17ae0 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 ount returned by
17af0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 sqlite3_total_c
17b00 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 hanges() include
17b10 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a s all changes.**
17b20 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 from all [CREAT
17b30 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
17b40 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e ger] contexts an
17b50 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 d changes made b
17b60 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 y.** [foreign ke
17b70 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 y actions]. Howe
17b80 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e ver,.** the coun
17b90 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 t does not inclu
17ba0 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 de changes used
17bb0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 to implement [RE
17bc0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e PLACE] constrain
17bd0 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 ts,.** do rollba
17be0 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f cks or ABORT pro
17bf0 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f cessing, or [DRO
17c00 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 P TABLE] process
17c10 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 ing. The.** cou
17c20 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c nt does not incl
17c30 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 ude rows of view
17c40 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b s that fire an [
17c50 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 INSTEAD OF trigg
17c60 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 er],.** though i
17c70 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 f the INSTEAD OF
17c80 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 trigger makes c
17c90 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 hanges of its ow
17ca0 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 n, those changes
17cb0 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 .** are counted
17cc0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .)^.** ^The sqli
17cd0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
17ce0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 s() function cou
17cf0 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 nts the changes
17d00 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 as soon as.** th
17d10 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 e statement that
17d20 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 makes them is c
17d30 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 ompleted (when t
17d40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e he statement han
17d50 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 dle.** is passed
17d60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
17d70 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
17d80 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 3_finalize()])..
17d90 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 **.** See also t
17da0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e he [sqlite3_chan
17db0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ges()] interface
17dc0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f , the.** [count_
17dd0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c changes pragma],
17de0 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f and the [total_
17df0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 changes() SQL fu
17e00 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
17e10 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
17e20 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
17e30 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
17e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
17e50 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 n.** while [sqli
17e60 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
17e70 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 s()] is running
17e80 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a then the value.*
17e90 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e * returned is un
17ea0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
17eb0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a not meaningful..
17ec0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 */.int sqlite3_t
17ed0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c otal_changes(sql
17ee0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
17ef0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 API3REF: Interru
17f00 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e pt A Long-Runnin
17f10 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 g Query.**.** ^T
17f20 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 his function cau
17f30 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 ses any pending
17f40 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 database operati
17f50 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a on to abort and.
17f60 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 ** return at its
17f70 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 earliest opport
17f80 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 unity. This rout
17f90 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 ine is typically
17fa0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 .** called in re
17fb0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 sponse to a user
17fc0 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 action such as
17fd0 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c pressing "Cancel
17fe0 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 ".** or Ctrl-C w
17ff0 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 here the user wa
18000 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 nts a long query
18010 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 operation to ha
18020 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c lt.** immediatel
18030 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 y..**.** ^It is
18040 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
18050 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 s routine from a
18060 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e thread differen
18070 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 t from the.** th
18080 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 read that is cur
18090 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 rently running t
180a0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 he database oper
180b0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a ation. But it.*
180c0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f * is not safe to
180d0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
180e0 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 ne with a [datab
180f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
18100 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 that.** is close
18110 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 d or might close
18120 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f before sqlite3_
18130 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 interrupt() retu
18140 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 rns..**.** ^If a
18150 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
18160 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 is very nearly f
18170 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 inished at the t
18180 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 ime when.** sqli
18190 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
181a0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 is called, then
181b0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 it might not hav
181c0 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 e an opportunity
181d0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 .** to be interr
181e0 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 upted and might
181f0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 continue to comp
18200 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 letion..**.** ^A
18210 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
18220 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 that is interrup
18230 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ted will return
18240 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
18250 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 T]..** ^If the i
18260 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f nterrupted SQL o
18270 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 peration is an I
18280 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
18290 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 r DELETE.** that
182a0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 is inside an ex
182b0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
182c0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 on, then the ent
182d0 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a ire transaction.
182e0 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 ** will be rolle
182f0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 d back automatic
18300 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ally..**.** ^The
18310 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
18320 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e pt(D) call is in
18330 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c effect until al
18340 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e l currently runn
18350 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
18360 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 ments on [databa
18370 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
18380 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 complete. ^Any
18390 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 new SQL stateme
183a0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
183b0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
183c0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
183d0 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 upt() call and b
183e0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 efore the .** ru
183f0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 nning statements
18400 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 reaches zero ar
18410 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 e interrupted as
18420 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 if they had bee
18430 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 n.** running pri
18440 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 or to the sqlite
18450 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
18460 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 ll. ^New SQL st
18470 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
18480 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
18490 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 er the running s
184a0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 tatement count r
184b0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a eaches zero are.
184c0 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 ** not effected
184d0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 by the sqlite3_i
184e0 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e nterrupt()..** ^
184f0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
18500 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 3_interrupt(D) t
18510 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 hat occurs when
18520 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e there are no run
18530 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
18540 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f ements is a no-o
18550 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 p and has no eff
18560 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 ect on SQL state
18570 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
18580 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
18590 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
185a0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 rrupt() call ret
185b0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 urns..**.** If t
185c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
185d0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 ection closes wh
185e0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 ile [sqlite3_int
185f0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 errupt()].** is
18600 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 running then bad
18610 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b things will lik
18620 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 ely happen..*/.v
18630 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 oid sqlite3_inte
18640 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b rrupt(sqlite3*);
18650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
18660 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
18670 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
18680 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a Is Complete.**.*
18690 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
186a0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 are useful duri
186b0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 ng command-line
186c0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 input to determi
186d0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 ne if the.** cur
186e0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 rently entered t
186f0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 ext seems to for
18700 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c m a complete SQL
18710 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a statement or.**
18720 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 if additional i
18730 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 nput is needed b
18740 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 efore sending th
18750 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 e text into.** S
18760 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e QLite for parsin
18770 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 g. ^These routi
18780 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 nes return 1 if
18790 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
187a0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 .** appears to b
187b0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c e a complete SQL
187c0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 statement. ^A
187d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 statement is jud
187e0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d ged to be.** com
187f0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 plete if it ends
18800 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f with a semicolo
18810 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e n token and is n
18820 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 ot a prefix of a
18830 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 .** well-formed
18840 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 CREATE TRIGGER s
18850 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 tatement. ^Semi
18860 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 colons that are
18870 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a embedded within.
18880 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 ** string litera
18890 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 ls or quoted ide
188a0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 ntifier names or
188b0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f comments are no
188c0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 t.** independent
188d0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 tokens (they ar
188e0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f e part of the to
188f0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 ken in which the
18900 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 y are.** embedde
18910 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e d) and thus do n
18920 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 ot count as a st
18930 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 atement terminat
18940 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 or. ^Whitespace
18950 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 .** and comments
18960 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 that follow the
18970 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e final semicolon
18980 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a are ignored..**
18990 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
189a0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 nes return 0 if
189b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
189c0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 incomplete. ^I
189d0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c f a.** memory al
189e0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 location fails,
189f0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 then SQLITE_NOME
18a00 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a M is returned..*
18a10 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
18a20 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 ines do not pars
18a30 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d e the SQL statem
18a40 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c ents thus.** wil
18a50 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e l not detect syn
18a60 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 tactically incor
18a70 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 rect SQL..**.**
18a80 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 ^(If SQLite has
18a90 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c not been initial
18aa0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ized using [sqli
18ab0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
18ac0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 ] prior .** to i
18ad0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f nvoking sqlite3_
18ae0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 complete16() the
18af0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 n sqlite3_initia
18b00 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
18b10 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c d.** automatical
18b20 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ly by sqlite3_co
18b30 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 mplete16(). If
18b40 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 that initializat
18b50 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 ion fails,.** th
18b60 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
18b70 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
18b80 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 _complete16() wi
18b90 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a ll be non-zero.*
18ba0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 * regardless of
18bb0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
18bc0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 he input SQL is
18bd0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a complete.)^.**.*
18be0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b * The input to [
18bf0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
18c00 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
18c10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
18c20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a UTF-8 string..*
18c30 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 *.** The input t
18c40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
18c50 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 ete16()] must be
18c60 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
18c70 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
18c80 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 ing in native by
18c90 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 te order..*/.int
18ca0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
18cb0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 e(const char *sq
18cc0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
18cd0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 complete16(const
18ce0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a void *sql);../*
18cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
18d00 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 gister A Callbac
18d10 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 k To Handle SQLI
18d20 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a TE_BUSY Errors.*
18d30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
18d40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 3_busy_handler(D
18d50 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 ,X,P) routine se
18d60 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 ts a callback fu
18d70 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 nction X.** that
18d80 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 might be invoke
18d90 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 d with argument
18da0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e P whenever.** an
18db0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 attempt is made
18dc0 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 to access a dat
18dd0 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f abase table asso
18de0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b ciated with.** [
18df0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18e00 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 ion] D when anot
18e10 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 her thread.** or
18e20 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 process has the
18e30 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a table locked..*
18e40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 * The sqlite3_bu
18e50 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 sy_handler() int
18e60 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
18e70 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b o implement.** [
18e80 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
18e90 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 eout()] and [PRA
18ea0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 GMA busy_timeout
18eb0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 ]..**.** ^If the
18ec0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 busy callback i
18ed0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 s NULL, then [SQ
18ee0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 LITE_BUSY].** is
18ef0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
18f00 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 ately upon encou
18f10 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b ntering the lock
18f20 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 . ^If the busy
18f30 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e callback.** is n
18f40 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ot NULL, then th
18f50 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 e callback might
18f60 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
18f70 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
18f80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
18f90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
18fa0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
18fb0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 a copy of the v
18fc0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 oid* pointer whi
18fd0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 ch.** is the thi
18fe0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
18ff0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
19000 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 ler(). ^The sec
19010 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
19020 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ** the busy hand
19030 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ler callback is
19040 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 the number of ti
19050 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 mes that the bus
19060 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a y handler has.**
19070 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f been invoked fo
19080 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 r the same locki
19090 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 ng event. ^If t
190a0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 he.** busy callb
190b0 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ack returns 0, t
190c0 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 hen no additiona
190d0 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d l attempts are m
190e0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 ade to.** access
190f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
19100 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 d [SQLITE_BUSY]
19110 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 is returned.** t
19120 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
19130 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 n..** ^If the ca
19140 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
19150 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e on-zero, then an
19160 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a other attempt.**
19170 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 is made to acce
19180 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
19190 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 and the cycle re
191a0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 peats..**.** The
191b0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 presence of a b
191c0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 usy handler does
191d0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 not guarantee t
191e0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 hat it will be i
191f0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 nvoked.** when t
19200 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e here is lock con
19210 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c tention. ^If SQL
19220 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 ite determines t
19230 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 hat invoking the
19240 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 busy.** handler
19250 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e could result in
19260 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 a deadlock, it
19270 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e will go ahead an
19280 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
19290 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 _BUSY].** to the
192a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 application ins
192b0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 tead of invoking
192c0 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 the .** busy ha
192d0 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 ndler..** Consid
192e0 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 er a scenario wh
192f0 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 ere one process
19300 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 is holding a rea
19310 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 d lock that.** i
19320 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 t is trying to p
19330 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 romote to a rese
19340 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a rved lock and.**
19350 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 a second proces
19360 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 s is holding a r
19370 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 eserved lock tha
19380 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a t it is trying.*
19390 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 * to promote to
193a0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 an exclusive loc
193b0 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 k. The first pr
193c0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f ocess cannot pro
193d0 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 ceed.** because
193e0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
193f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 the second and
19400 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
19410 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f ss cannot.** pro
19420 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 ceed because it
19430 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
19440 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 e first. If bot
19450 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 h processes.** i
19460 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 nvoke the busy h
19470 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 andlers, neither
19480 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 will make any p
19490 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 rogress. Theref
194a0 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 ore,.** SQLite r
194b0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 eturns [SQLITE_B
194c0 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 USY] for the fir
194d0 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 st process, hopi
194e0 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 ng that this.**
194f0 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 will induce the
19500 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f first process to
19510 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 release its rea
19520 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 d lock and allow
19530 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 .** the second p
19540 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 rocess to procee
19550 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 d..**.** ^The de
19560 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 fault busy callb
19570 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a ack is NULL..**.
19580 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f ** ^(There can o
19590 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
195a0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 busy handler def
195b0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a ined for each.**
195c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
195d0 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 ction]. Setting
195e0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 a new busy hand
195f0 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a ler clears any.*
19600 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 * previously set
19610 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f handler.)^ ^No
19620 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 te that calling
19630 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
19640 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 meout()].** or e
19650 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d valuating [PRAGM
19660 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e A busy_timeout=N
19670 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 ] will change th
19680 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 e.** busy handle
19690 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 r and thus clear
196a0 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 any previously
196b0 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 set busy handler
196c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 ..**.** The busy
196d0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
196e0 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 not take any ac
196f0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 tions which modi
19700 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 fy the.** databa
19710 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
19720 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
19730 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e usy handler. In
19740 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a other words,.**
19750 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
19760 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 r is not reentra
19770 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 nt. Any such ac
19780 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 tions.** result
19790 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
197a0 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 avior..** .** A
197b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 busy handler mus
197c0 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 t not close the
197d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
197e0 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 ion.** or [prepa
197f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
19800 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
19810 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f busy handler..*/
19820 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 .int sqlite3_bus
19830 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 y_handler(sqlite
19840 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 3*, int(*)(void*
19850 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a ,int), void*);..
19860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
19870 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f Set A Busy Timeo
19880 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 ut.**.** ^This r
19890 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 outine sets a [s
198a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
198b0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c ler | busy handl
198c0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a er] that sleeps.
198d0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 ** for a specifi
198e0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d ed amount of tim
198f0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 e when a table i
19900 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 s locked. ^The
19910 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 handler.** will
19920 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 sleep multiple t
19930 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 imes until at le
19940 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 ast "ms" millise
19950 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e conds of sleepin
19960 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 g.** have accumu
19970 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 lated. ^After a
19980 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c t least "ms" mil
19990 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
199a0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 eping,.** the ha
199b0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 ndler returns 0
199c0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 which causes [sq
199d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f lite3_step()] to
199e0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 return.** [SQLI
199f0 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 TE_BUSY]..**.**
19a00 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f ^Calling this ro
19a10 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 utine with an ar
19a20 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e gument less than
19a30 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 or equal to zer
19a40 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 o.** turns off a
19a50 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 ll busy handlers
19a60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 ..**.** ^(There
19a70 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
19a80 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
19a90 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c r for a particul
19aa0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ar.** [database
19ab0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 connection] any
19ac0 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 any given moment
19ad0 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 . If another bu
19ae0 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 sy handler.** wa
19af0 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e s defined (usin
19b00 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
19b10 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f handler()]) prio
19b20 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 r to calling.**
19b30 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 this routine, th
19b40 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 at other busy ha
19b50 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 ndler is cleared
19b60 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c .)^.**.** See al
19b70 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 so: [PRAGMA bus
19b80 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e y_timeout].*/.in
19b90 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 t sqlite3_busy_t
19ba0 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c imeout(sqlite3*,
19bb0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a int ms);../*.**
19bc0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 CAPI3REF: Conve
19bd0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 nience Routines
19be0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 For Running Quer
19bf0 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ies.**.** This i
19c00 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 s a legacy inter
19c10 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 face that is pre
19c20 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 served for backw
19c30 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
19c40 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 ty..** Use of th
19c50 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
19c60 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e not recommended.
19c70 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f .**.** Definitio
19c80 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 n: A <b>result t
19c90 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f able</b> is memo
19ca0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ry data structur
19cb0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 e created by the
19cc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 .** [sqlite3_get
19cd0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 _table()] interf
19ce0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 ace. A result t
19cf0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 able records the
19d00 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 .** complete que
19d10 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 ry results from
19d20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 one or more quer
19d30 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ies..**.** The t
19d40 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c able conceptuall
19d50 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f y has a number o
19d60 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d f rows and colum
19d70 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 ns. But.** thes
19d80 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f e numbers are no
19d90 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 t part of the re
19da0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c sult table itsel
19db0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d f. These.** num
19dc0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 bers are obtaine
19dd0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c d separately. L
19de0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 et N be the numb
19df0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e er of rows.** an
19e00 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 d M be the numbe
19e10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a r of columns..**
19e20 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
19e30 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f le is an array o
19e40 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 f pointers to ze
19e50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
19e60 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 F-8 strings..**
19e70 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a There are (N+1)*
19e80 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 M elements in th
19e90 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 e array. The fi
19ea0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 rst M pointers p
19eb0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d oint.** to zero-
19ec0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
19ed0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e gs that contain
19ee0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 the names of th
19ef0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 e columns..** Th
19f00 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 e remaining entr
19f10 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f ies all point to
19f20 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 query results.
19f30 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 NULL values res
19f40 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 ult.** in NULL p
19f50 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 ointers. All ot
19f60 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 her values are i
19f70 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 n their UTF-8 ze
19f80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
19f90 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e string represen
19fa0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e tation as return
19fb0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
19fc0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a olumn_text()]..*
19fd0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
19fe0 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 ble might consis
19ff0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 t of one or more
1a000 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1a010 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ons..** It is no
1a020 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 t safe to pass a
1a030 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 result table di
1a040 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 rectly to [sqlit
1a050 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 e3_free()]..** A
1a060 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 result table sh
1a070 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 ould be dealloca
1a080 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
1a090 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
1a0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 ..**.** ^(As an
1a0b0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 example of the r
1a0c0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d esult table form
1a0d0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 at, suppose a qu
1a0e0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ery result.** is
1a0f0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
1a100 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1a110 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e pre>.** N
1a120 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 ame | Age
1a130 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d .** -----
1a140 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1a150 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 --.** Ali
1a160 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a ce | 43.**
1a170 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 Bob
1a180 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 | 28.**
1a190 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c Cindy |
1a1a0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 21.** </pre></b
1a1b0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1a1c0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 There are two c
1a1d0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 olumn (M==2) and
1a1e0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d three rows (N==
1a1f0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 3). Thus the.**
1a200 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 result table ha
1a210 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 s 8 entries. Su
1a220 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 ppose the result
1a230 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 table is stored
1a240 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 .** in an array
1a250 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 names azResult.
1a260 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 Then azResult h
1a270 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e olds this conten
1a280 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 t:.**.** <blockq
1a290 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
1a2a0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1a2b0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 1;0] = "Name";.*
1a2c0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1a2d0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 t[1] = "Age"
1a2e0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1a2f0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 sult[2] = "A
1a300 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 lice";.**
1a310 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d azResult[3]
1a320 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 = "43";.**
1a330 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1a340 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 4] = "Bob";.**
1a350 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1a360 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 91;5] = "28";.**
1a370 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1a380 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 [6] = "Cindy
1a390 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1a3a0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 esult[7] = "
1a3b0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 21";.** </pre></
1a3c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
1a3d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1a3e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e _get_table() fun
1a3f0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 ction evaluates
1a400 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 one or more.** s
1a410 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 emicolon-separat
1a420 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ed SQL statement
1a430 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 s in the zero-te
1a440 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a rminated UTF-8.*
1a450 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 * string of its
1a460 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 2nd parameter an
1a470 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 d returns a resu
1a480 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a lt table to the.
1a490 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e ** pointer given
1a4a0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 in its 3rd para
1a4b0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 meter..**.** Aft
1a4c0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 er the applicati
1a4d0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 on has finished
1a4e0 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 with the result
1a4f0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 from sqlite3_get
1a500 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 _table(),.** it
1a510 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 must pass the re
1a520 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 sult table point
1a530 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 er to sqlite3_fr
1a540 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 ee_table() in or
1a550 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 der to.** releas
1a560 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 e the memory tha
1a570 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 t was malloced.
1a580 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
1a590 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 way the.** [sqli
1a5a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 te3_malloc()] ha
1a5b0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c ppens within sql
1a5c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1a5d0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a , the calling.**
1a5e0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e function must n
1a5f0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b ot try to call [
1a600 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1a610 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a directly. Only.
1a620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
1a630 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c _table()] is abl
1a640 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 e to release the
1a650 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 memory properly
1a660 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a and safely..**.
1a670 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ** The sqlite3_g
1a680 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 et_table() inter
1a690 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
1a6a0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 ted as a wrapper
1a6b0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 around.** [sqli
1a6c0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 te3_exec()]. Th
1a6d0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
1a6e0 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f ble() routine do
1a6f0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 es not have acce
1a700 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 ss.** to any int
1a710 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 ernal data struc
1a720 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e tures of SQLite.
1a730 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 It uses only t
1a740 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 he public.** int
1a750 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 erface defined h
1a760 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 ere. As a conse
1a770 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 quence, errors t
1a780 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 hat occur in the
1a790 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 .** wrapper laye
1a7a0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 r outside of the
1a7b0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 internal [sqlit
1a7c0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 e3_exec()] call
1a7d0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 are not.** refle
1a7e0 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 cted in subseque
1a7f0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
1a800 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
1a810 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 or.** [sqlite3_e
1a820 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 rrmsg()]..*/.int
1a830 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1a840 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 le(. sqlite3 *d
1a850 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 b, /* A
1a860 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 n open database
1a870 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1a880 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 *zSql, /* SQ
1a890 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 L to be evaluate
1a8a0 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 d */. char ***p
1a8b0 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 azResult, /*
1a8c0 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 Results of the q
1a8d0 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 uery */. int *p
1a8e0 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 nRow,
1a8f0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 /* Number of res
1a900 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e ult rows written
1a910 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a here */. int *
1a920 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 pnColumn,
1a930 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
1a940 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 sult columns wri
1a950 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 tten here */. c
1a960 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 har **pzErrmsg
1a970 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 /* Error ms
1a980 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a g written here *
1a990 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 /.);.void sqlite
1a9a0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 3_free_table(cha
1a9b0 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a r **result);../*
1a9c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f .** CAPI3REF: Fo
1a9d0 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 rmatted String P
1a9e0 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e rinting Function
1a9f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f s.**.** These ro
1aa00 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d utines are work-
1aa10 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 alikes of the "p
1aa20 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 rintf()" family
1aa30 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 of functions.**
1aa40 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
1aa50 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a d C library..**.
1aa60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1aa70 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 mprintf() and sq
1aa80 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 lite3_vmprintf()
1aa90 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 routines write
1aaa0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 their.** results
1aab0 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
1aac0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
1aad0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a te3_malloc()]..*
1aae0 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 * The strings re
1aaf0 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 turned by these
1ab00 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f two routines sho
1ab10 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 uld be.** releas
1ab20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
1ab30 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 ree()]. ^Both r
1ab40 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 outines return a
1ab50 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
1ab60 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c if [sqlite3_mal
1ab70 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 loc()] is unable
1ab80 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f to allocate eno
1ab90 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f ugh.** memory to
1aba0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 hold the result
1abb0 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a ing string..**.*
1abc0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f * ^(The sqlite3_
1abd0 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 snprintf() routi
1abe0 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ne is similar to
1abf0 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 "snprintf()" fr
1ac00 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 om.** the standa
1ac10 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 rd C library. T
1ac20 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 he result is wri
1ac30 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a tten into the.**
1ac40 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 buffer supplied
1ac50 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
1ac60 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 arameter whose s
1ac70 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a ize is given by.
1ac80 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 ** the first par
1ac90 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 ameter. Note tha
1aca0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 t the order of t
1acb0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 he.** first two
1acc0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 parameters is re
1acd0 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 versed from snpr
1ace0 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 intf().)^ This
1acf0 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 is an.** histori
1ad00 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 cal accident tha
1ad10 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 t cannot be fixe
1ad20 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 d without breaki
1ad30 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 ng.** backwards
1ad40 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 compatibility.
1ad50 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 ^(Note also that
1ad60 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1ad70 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 f().** returns a
1ad80 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 pointer to its
1ad90 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f buffer instead o
1ada0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a f the number of.
1adb0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 ** characters ac
1adc0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 tually written i
1add0 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 nto the buffer.)
1ade0 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ^ We admit that
1adf0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
1ae00 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 f characters wri
1ae10 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 tten would be a
1ae20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 more useful retu
1ae30 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 rn.** value but
1ae40 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 we cannot change
1ae50 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
1ae60 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 ion of sqlite3_s
1ae70 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 nprintf().** now
1ae80 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e without breakin
1ae90 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e g compatibility.
1aea0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 .**.** ^As long
1aeb0 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 as the buffer si
1aec0 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 ze is greater th
1aed0 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 an zero, sqlite3
1aee0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 _snprintf().** g
1aef0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
1af00 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 he buffer is alw
1af10 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
1af20 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ted. ^The first
1af30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e .** parameter "n
1af40 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 " is the total s
1af50 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
1af60 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 r, including spa
1af70 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 ce for.** the ze
1af80 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 ro terminator.
1af90 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 So the longest s
1afa0 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 tring that can b
1afb0 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 e completely.**
1afc0 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 written will be
1afd0 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a n-1 characters..
1afe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1aff0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 e3_vsnprintf() r
1b000 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 outine is a vara
1b010 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 rgs version of s
1b020 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1b030 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 )..**.** These r
1b040 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c outines all impl
1b050 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 ement some addit
1b060 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 ional formatting
1b070 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 .** options that
1b080 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 are useful for
1b090 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c constructing SQL
1b0a0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
1b0b0 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c All of the usual
1b0c0 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 printf() format
1b0d0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 ting options app
1b0e0 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e ly. In addition
1b0f0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 , there.** is ar
1b100 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e e "%q", "%Q", an
1b110 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a d "%z" options..
1b120 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f **.** ^(The %q o
1b130 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
1b140 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 %s in that it s
1b150 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c ubstitutes a nul
1b160 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
1b170 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 tring from the a
1b180 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 rgument list. B
1b190 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c ut %q also doubl
1b1a0 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 es every '\'' ch
1b1b0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 aracter..** %q i
1b1c0 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 s designed for u
1b1d0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 se inside a stri
1b1e0 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 ng literal.)^ B
1b1f0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 y doubling each
1b200 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 '\''.** characte
1b210 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 r it escapes tha
1b220 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 t character and
1b230 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 allows it to be
1b240 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a inserted into.**
1b250 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a the string..**.
1b260 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ** For example,
1b270 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e assume the strin
1b280 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 g variable zText
1b290 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 contains text a
1b2a0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
1b2b0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1b2c0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 e>.** char *zTe
1b2d0 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 xt = "It's a hap
1b2e0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 py day!";.** </p
1b2f0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1b300 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 .**.** One can u
1b310 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 se this text in
1b320 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
1b330 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
1b340 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1b350 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
1b360 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
1b370 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
1b380 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
1b390 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a '%q')", zText);.
1b3a0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
1b3b0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
1b3c0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
1b3d0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
1b3e0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1b3f0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 te>.**.** Becaus
1b400 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 e the %q format
1b410 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 string is used,
1b420 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 the '\'' charact
1b430 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 er in zText.** i
1b440 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 s escaped and th
1b450 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 e SQL generated
1b460 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a is as follows:.*
1b470 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1b480 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
1b490 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
1b4a0 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 LUES('It''s a ha
1b4b0 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f ppy day!').** </
1b4c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1b4d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 >.**.** This is
1b4e0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 correct. Had we
1b4f0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 used %s instead
1b500 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 of %q, the gene
1b510 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 rated SQL.** wou
1b520 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c ld have looked l
1b530 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
1b540 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1b550 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 >.** INSERT INT
1b560 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
1b570 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 'It's a happy da
1b580 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c y!');.** </pre><
1b590 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1b5a0 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 ** This second e
1b5b0 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c xample is an SQL
1b5c0 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 syntax error.
1b5d0 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c As a general rul
1b5e0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 e you should.**
1b5f0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e always use %q in
1b600 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e stead of %s when
1b610 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 inserting text
1b620 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 into a string li
1b630 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 teral..**.** ^(T
1b640 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 he %Q option wor
1b650 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 ks like %q excep
1b660 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 t it also adds s
1b670 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f ingle quotes aro
1b680 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 und.** the outsi
1b690 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 de of the total
1b6a0 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f string. Additio
1b6b0 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 nally, if the pa
1b6c0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a rameter in the.*
1b6d0 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 * argument list
1b6e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
1b6f0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 r, %Q substitute
1b700 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c s the text "NULL
1b710 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 " (without.** si
1b720 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 ngle quotes).)^
1b730 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 So, for example
1b740 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a , one could say:
1b750 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1b760 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
1b770 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 r *zSQL = sqlite
1b780 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 3_mprintf("INSER
1b790 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c T INTO table VAL
1b7a0 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 UES(%Q)", zText)
1b7b0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
1b7c0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
1b7d0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
1b7e0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
1b7f0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1b800 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 uote>.**.** The
1b810 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 code above will
1b820 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 render a correct
1b830 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
1b840 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 n the zSQL.** va
1b850 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 riable even if t
1b860 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c he zText variabl
1b870 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e e is a NULL poin
1b880 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ter..**.** ^(The
1b890 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 "%z" formatting
1b8a0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
1b8b0 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 ke "%s" but with
1b8c0 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e the.** addition
1b8d0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 that after the
1b8e0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 string has been
1b8f0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 read and copied
1b900 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 into.** the resu
1b910 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 lt, [sqlite3_fre
1b920 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f e()] is called o
1b930 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 n the input stri
1b940 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 ng.)^.*/.char *s
1b950 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 qlite3_mprintf(c
1b960 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b onst char*,...);
1b970 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 .char *sqlite3_v
1b980 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
1b990 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 ar*, va_list);.c
1b9a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 har *sqlite3_snp
1b9b0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c rintf(int,char*,
1b9c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e const char*, ...
1b9d0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
1b9e0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 _vsnprintf(int,c
1b9f0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
1ba00 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a , va_list);../*.
1ba10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
1ba20 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 ory Allocation S
1ba30 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 ubsystem.**.** T
1ba40 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 he SQLite core u
1ba50 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 ses these three
1ba60 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c routines for all
1ba70 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 of its own.** i
1ba80 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 nternal memory a
1ba90 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
1baa0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 "Core" in the p
1bab0 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
1bac0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 .** does not inc
1bad0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 lude operating-s
1bae0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 ystem specific V
1baf0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
1bb00 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f n. The.** Windo
1bb10 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 ws VFS uses nati
1bb20 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 ve malloc() and
1bb30 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 free() for some
1bb40 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a operations..**.*
1bb50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d * ^The sqlite3_m
1bb60 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 alloc() routine
1bb70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1bb80 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 r to a block.**
1bb90 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 of memory at lea
1bba0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 st N bytes in le
1bbb0 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 ngth, where N is
1bbc0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
1bbd0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d ** ^If sqlite3_m
1bbe0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c alloc() is unabl
1bbf0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 e to obtain suff
1bc00 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d icient free.** m
1bc10 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e emory, it return
1bc20 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
1bc30 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d . ^If the param
1bc40 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c eter N to.** sql
1bc50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 ite3_malloc() is
1bc60 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 zero or negativ
1bc70 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d e then sqlite3_m
1bc80 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a alloc() returns.
1bc90 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
1bca0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e r..**.** ^Callin
1bcb0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 g sqlite3_free()
1bcc0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
1bcd0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 previously retur
1bce0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 ned.** by sqlite
1bcf0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
1bd00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
1bd10 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 releases that me
1bd20 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 mory so.** that
1bd30 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 it might be reus
1bd40 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 ed. ^The sqlite
1bd50 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 3_free() routine
1bd60 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 is.** a no-op i
1bd70 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 f is called with
1bd80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1bd90 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c Passing a NULL
1bda0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 pointer.** to s
1bdb0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
1bdc0 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 harmless. Afte
1bdd0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d r being freed, m
1bde0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 emory.** should
1bdf0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 neither be read
1be00 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 nor written. Ev
1be10 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 en reading previ
1be20 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d ously freed.** m
1be30 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 emory might resu
1be40 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 lt in a segmenta
1be50 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 tion fault or ot
1be60 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
1be70 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 ..** Memory corr
1be80 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e uption, a segmen
1be90 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 tation fault, or
1bea0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
1beb0 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 ror.** might res
1bec0 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 ult if sqlite3_f
1bed0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ree() is called
1bee0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 with a non-NULL
1bef0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 pointer that.**
1bf00 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 was not obtained
1bf10 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
1bf20 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 lloc() or sqlite
1bf30 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 3_realloc()..**.
1bf40 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
1bf50 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 _realloc() inter
1bf60 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
1bf70 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 resize a.** pri
1bf80 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 or memory alloca
1bf90 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 tion to be at le
1bfa0 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 ast N bytes, whe
1bfb0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 re N is the.** s
1bfc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
1bfd0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c The memory all
1bfe0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 ocation to be re
1bff0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 sized is the fir
1c000 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e st.** parameter.
1c010 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 )^ ^ If the firs
1c020 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
1c030 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1c040 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f .** is a NULL po
1c050 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 inter then its b
1c060 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 ehavior is ident
1c070 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a ical to calling.
1c080 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
1c090 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 c(N) where N is
1c0a0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
1c0b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1c0c0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 realloc()..** ^I
1c0d0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 f the second par
1c0e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1c0f0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 3_realloc() is z
1c100 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 ero or.** negati
1c110 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ve then the beha
1c120 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 vior is exactly
1c130 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c the same as call
1c140 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 ing.** sqlite3_f
1c150 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 ree(P) where P i
1c160 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 s the first para
1c170 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1c180 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e _realloc()..** ^
1c190 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1c1a0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e ) returns a poin
1c1b0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 ter to a memory
1c1c0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
1c1d0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
1c1e0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c s in size or NUL
1c1f0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 L if sufficient
1c200 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 memory is unavai
1c210 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 lable..** ^If M
1c220 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 is the size of t
1c230 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
1c240 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c ion, then min(N,
1c250 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 M) bytes.** of t
1c260 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
1c270 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 ion are copied i
1c280 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e nto the beginnin
1c290 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 g of buffer retu
1c2a0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 rned.** by sqlit
1c2b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 e3_realloc() and
1c2c0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
1c2d0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a ation is freed..
1c2e0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 ** ^If sqlite3_r
1c2f0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 ealloc() returns
1c300 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 NULL, then the
1c310 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
1c320 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 .** is not freed
1c330 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d ..**.** ^The mem
1c340 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 ory returned by
1c350 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1c360 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 and sqlite3_rea
1c370 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 lloc().** is alw
1c380 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 ays aligned to a
1c390 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 t least an 8 byt
1c3a0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 e boundary, or t
1c3b0 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f o a.** 4 byte bo
1c3c0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 undary if the [S
1c3d0 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 QLITE_4_BYTE_ALI
1c3e0 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d GNED_MALLOC] com
1c3f0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
1c400 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a ion is used..**.
1c410 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 ** In SQLite ver
1c420 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 sion 3.5.0 and 3
1c430 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 .5.1, it was pos
1c440 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a sible to define.
1c450 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d ** the SQLITE_OM
1c460 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 IT_MEMORY_ALLOCA
1c470 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 TION which would
1c480 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 cause the built
1c490 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 -in.** implement
1c4a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 ation of these r
1c4b0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d outines to be om
1c4c0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 itted. That cap
1c4d0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f ability.** is no
1c4e0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 longer provided
1c4f0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e . Only built-in
1c500 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
1c510 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a rs can be used..
1c520 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 **.** Prior to S
1c530 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
1c540 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 7.10, the Window
1c550 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c s OS interface l
1c560 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 ayer called.** t
1c570 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 he system malloc
1c580 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 () and free() di
1c590 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 rectly when conv
1c5a0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 erting.** filena
1c5b0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 mes between the
1c5c0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 UTF-8 encoding u
1c5d0 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a sed by SQLite.**
1c5e0 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 and whatever fi
1c5f0 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 lename encoding
1c600 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 is used by the p
1c610 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 articular Window
1c620 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f s.** installatio
1c630 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 n. Memory alloc
1c640 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 ation errors wer
1c650 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a e detected, but.
1c660 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 ** they were rep
1c670 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 orted back as [S
1c680 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
1c690 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f or.** [SQLITE_IO
1c6a0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e ERR] rather than
1c6b0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
1c6c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 .**.** The point
1c6d0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 er arguments to
1c6e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1c6f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
1c700 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 alloc()].** must
1c710 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 be either NULL
1c720 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 or else pointers
1c730 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
1c740 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 prior.** invoca
1c750 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
1c760 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 _malloc()] or [s
1c770 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1c780 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e ] that have.** n
1c790 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 ot yet been rele
1c7a0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ased..**.** The
1c7b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
1c7c0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 not read or wri
1c7d0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a te any part of.*
1c7e0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d * a block of mem
1c7f0 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 ory after it has
1c800 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 been released u
1c810 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
1c820 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c _free()] or [sql
1c830 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e ite3_realloc()].
1c840 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
1c850 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 3_malloc(int);.v
1c860 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 oid *sqlite3_rea
1c870 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 lloc(void*, int)
1c880 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 ;.void sqlite3_f
1c890 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a ree(void*);../*.
1c8a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
1c8b0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 ory Allocator St
1c8c0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 atistics.**.** S
1c8d0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 QLite provides t
1c8e0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 hese two interfa
1c8f0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e ces for reportin
1c900 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a g on the status.
1c910 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
1c920 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 e3_malloc()], [s
1c930 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 qlite3_free()],
1c940 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
1c950 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 lloc()].** routi
1c960 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 nes, which form
1c970 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d the built-in mem
1c980 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
1c990 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 ubsystem..**.**
1c9a0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 ^The [sqlite3_me
1c9b0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 mory_used()] rou
1c9c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
1c9d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
1c9e0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 .** of memory cu
1c9f0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 rrently outstand
1ca00 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 ing (malloced bu
1ca10 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a t not freed)..**
1ca20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d ^The [sqlite3_m
1ca30 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
1ca40 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 )] routine retur
1ca50 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a ns the maximum.*
1ca60 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 * value of [sqli
1ca70 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1ca80 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 )] since the hig
1ca90 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 h-water mark.**
1caa0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 was last reset.
1cab0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 ^The values ret
1cac0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
1cad0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
1cae0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
1caf0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
1cb00 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 r()] include any
1cb10 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 overhead.** add
1cb20 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 ed by SQLite in
1cb30 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 its implementati
1cb40 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d on of [sqlite3_m
1cb50 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 alloc()],.** but
1cb60 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 not overhead ad
1cb70 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 ded by the any u
1cb80 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d nderlying system
1cb90 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 library.** rout
1cba0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 ines that [sqlit
1cbb0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 e3_malloc()] may
1cbc0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 call..**.** ^Th
1cbd0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 e memory high-wa
1cbe0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 ter mark is rese
1cbf0 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 t to the current
1cc00 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 value of.** [sq
1cc10 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
1cc20 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 d()] if and only
1cc30 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
1cc40 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
1cc50 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
1cc60 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e r()] is true. ^
1cc70 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
1cc80 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 ed.** by [sqlite
1cc90 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
1cca0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 er(1)] is the hi
1ccb0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
1ccc0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 prior to the re
1ccd0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f set..*/.sqlite3_
1cce0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
1ccf0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b mory_used(void);
1cd00 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
1cd10 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1cd20 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 ghwater(int rese
1cd30 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 tFlag);../*.** C
1cd40 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d API3REF: Pseudo-
1cd50 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 Random Number Ge
1cd60 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 nerator.**.** SQ
1cd70 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 Lite contains a
1cd80 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 high-quality pse
1cd90 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 udo-random numbe
1cda0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e r generator (PRN
1cdb0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 G) used to.** se
1cdc0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 lect random [ROW
1cdd0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 ID | ROWIDs] whe
1cde0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 n inserting new
1cdf0 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 records into a t
1ce00 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 able that.** alr
1ce10 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 eady uses the la
1ce20 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b rgest possible [
1ce30 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e ROWID]. The PRN
1ce40 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 G is also used f
1ce50 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d or.** the build-
1ce60 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 in random() and
1ce70 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c randomblob() SQL
1ce80 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 functions. Thi
1ce90 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
1cea0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f ws.** applicatio
1ceb0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 ns to access the
1cec0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f same PRNG for o
1ced0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a ther purposes..*
1cee0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 *.** ^A call to
1cef0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f this routine sto
1cf00 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 res N bytes of r
1cf10 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 andomness into b
1cf20 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 49 66 20 uffer P..** ^If
1cf30 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f N is less than o
1cf40 6e 65 2c 20 74 68 65 6e 20 50 20 63 61 6e 20 62 ne, then P can b
1cf50 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
1cf60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 ..**.** ^If this
1cf70 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 routine has not
1cf80 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 been previously
1cf90 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 called or if th
1cfa0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 e previous.** ca
1cfb0 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 ll had N less th
1cfc0 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 74 68 65 an one, then the
1cfd0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 PRNG is seeded
1cfe0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 using randomness
1cff0 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f .** obtained fro
1d000 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 m the xRandomnes
1d010 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
1d020 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
1d030 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
1d040 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 ^If the previou
1d050 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 s call to this r
1d060 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 outine had an N
1d070 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 74 68 65 of 1 or more the
1d080 6e 0a 2a 2a 20 74 68 65 20 70 73 65 75 64 6f 2d n.** the pseudo-
1d090 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 randomness is ge
1d0a0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 nerated.** inter
1d0b0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 nally and withou
1d0c0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 t recourse to th
1d0d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 e [sqlite3_vfs]
1d0e0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d xRandomness.** m
1d0f0 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 ethod..*/.void s
1d100 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 qlite3_randomnes
1d110 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 s(int N, void *P
1d120 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1d130 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 EF: Compile-Time
1d140 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 Authorization C
1d150 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e allbacks.**.** ^
1d160 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 This routine reg
1d170 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 isters an author
1d180 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 izer callback wi
1d190 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a th a particular.
1d1a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1d1b0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 nection], suppli
1d1c0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ed in the first
1d1d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
1d1e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1d1f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
1d200 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e as SQL statemen
1d210 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d ts are being com
1d220 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c piled.** by [sql
1d230 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
1d240 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 or its variants
1d250 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1d260 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 _v2()],.** [sqli
1d270 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
1d280 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
1d290 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 epare16_v2()].
1d2a0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 ^At various.** p
1d2b0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 oints during the
1d2c0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f compilation pro
1d2d0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 cess, as logic i
1d2e0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a s being created.
1d2f0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 ** to perform va
1d300 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 rious actions, t
1d310 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1d320 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
1d330 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 d to.** see if t
1d340 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 hose actions are
1d350 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 allowed. ^The
1d360 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1d370 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 ack should.** re
1d380 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
1d390 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 to allow the ac
1d3a0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 tion, [SQLITE_IG
1d3b0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f NORE] to disallo
1d3c0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 w the.** specifi
1d3d0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c c action but all
1d3e0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ow the SQL state
1d3f0 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 ment to continue
1d400 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c to be.** compil
1d410 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 ed, or [SQLITE_D
1d420 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 ENY] to cause th
1d430 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 e entire SQL sta
1d440 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 tement to be.**
1d450 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e rejected with an
1d460 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 error. ^If the
1d470 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1d480 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 back returns.**
1d490 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 any value other
1d4a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e than [SQLITE_IGN
1d4b0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b ORE], [SQLITE_OK
1d4c0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 ], or [SQLITE_DE
1d4d0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 NY].** then the
1d4e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1d4f0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 _v2()] or equiva
1d500 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 lent call that t
1d510 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 riggered.** the
1d520 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 authorizer will
1d530 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 fail with an err
1d540 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a or message..**.*
1d550 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 * When the callb
1d560 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
1d570 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 ITE_OK], that me
1d580 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f ans the operatio
1d590 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 n.** requested i
1d5a0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 s ok. ^When the
1d5b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1d5c0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c s [SQLITE_DENY],
1d5d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
1d5e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
1d5f0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c r equivalent cal
1d600 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
1d610 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
1d620 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 er will fail wit
1d630 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 h an error messa
1d640 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 ge explaining th
1d650 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 at.** access is
1d660 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e denied. .**.** ^
1d670 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
1d680 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
1d690 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
1d6a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
1d6b0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 third.** paramet
1d6c0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
1d6d0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1d6e0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 () interface. ^T
1d6f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1d700 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ter.** to the ca
1d710 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
1d720 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 eger [SQLITE_COP
1d730 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d Y | action code]
1d740 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a that specifies.
1d750 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 ** the particula
1d760 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 r action to be a
1d770 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 uthorized. ^The
1d780 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 third through si
1d790 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a xth parameters.*
1d7a0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
1d7b0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 k are zero-termi
1d7c0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 nated strings th
1d7d0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 at contain addit
1d7e0 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 ional.** details
1d7f0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f about the actio
1d800 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
1d810 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
1d820 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 e action code is
1d830 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a [SQLITE_READ].*
1d840 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 * and the callba
1d850 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
1d860 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 TE_IGNORE] then
1d870 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
1d880 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 statement] stat
1d890 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 ement is constru
1d8a0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 cted to substitu
1d8b0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c te.** a NULL val
1d8c0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 ue in place of t
1d8d0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 he table column
1d8e0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a that would have.
1d8f0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 ** been read if
1d900 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 [SQLITE_OK] had
1d910 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 been returned.
1d920 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f The [SQLITE_IGNO
1d930 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 RE].** return ca
1d940 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e n be used to den
1d950 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 y an untrusted u
1d960 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e ser access to in
1d970 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 dividual.** colu
1d980 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a mns of a table..
1d990 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f ** ^If the actio
1d9a0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 n code is [SQLIT
1d9b0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 E_DELETE] and th
1d9c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
1d9d0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 ns.** [SQLITE_IG
1d9e0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b NORE] then the [
1d9f0 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f DELETE] operatio
1da00 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 n proceeds but t
1da10 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 he.** [truncate
1da20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 optimization] is
1da30 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c disabled and al
1da40 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 l rows are delet
1da50 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e ed individually.
1da60 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 .**.** An author
1da70 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 izer is used whe
1da80 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
1da90 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a re | preparing].
1daa0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
1dab0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 s from an untrus
1dac0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 ted source, to e
1dad0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 nsure that the S
1dae0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
1daf0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 do not try to a
1db00 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 ccess data they
1db10 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 are not allowed
1db20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 to see, or that
1db30 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 they do not.** t
1db40 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 ry to execute ma
1db50 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e licious statemen
1db60 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 ts that damage t
1db70 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f he database. Fo
1db80 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e r.** example, an
1db90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 application may
1dba0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f allow a user to
1dbb0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 enter arbitrary
1dbc0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 .** SQL queries
1dbd0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 for evaluation b
1dbe0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 y a database. B
1dbf0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ut the applicati
1dc00 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 on does.** not w
1dc10 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 ant the user to
1dc20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 be able to make
1dc30 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 arbitrary change
1dc40 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 s to the.** data
1dc50 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 base. An author
1dc60 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 izer could then
1dc70 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 be put in place
1dc80 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 while the.** use
1dc90 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 r-entered SQL is
1dca0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f being [sqlite3_
1dcb0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 prepare | prepar
1dcc0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 ed] that.** disa
1dcd0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 llows everything
1dce0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d except [SELECT]
1dcf0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
1dd00 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
1dd10 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f that need to pro
1dd20 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e cess SQL from un
1dd30 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a trusted sources.
1dd40 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f ** might also co
1dd50 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 nsider lowering
1dd60 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 resource limits
1dd70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c using [sqlite3_l
1dd80 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c imit()].** and l
1dd90 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 imiting database
1dda0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 size using the
1ddb0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d [max_page_count]
1ddc0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 [PRAGMA].** in
1ddd0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e addition to usin
1dde0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e g an authorizer.
1ddf0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 .**.** ^(Only a
1de00 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 single authorize
1de10 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 r can be in plac
1de20 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 e on a database
1de30 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 connection.** at
1de40 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 a time. Each c
1de50 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
1de60 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 et_authorizer ov
1de70 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 errides the.** p
1de80 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 revious call.)^
1de90 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 ^Disable the au
1dea0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 thorizer by inst
1deb0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 alling a NULL ca
1dec0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 llback..** The a
1ded0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 uthorizer is dis
1dee0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
1def0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 ..**.** The auth
1df00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1df10 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
1df20 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
1df30 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
1df40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1df50 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
1df60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1df70 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 lback..** Note t
1df80 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hat [sqlite3_pre
1df90 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
1dfa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1dfb0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 both modify thei
1dfc0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
1dfd0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 nnections for th
1dfe0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f e meaning of "mo
1dff0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 dify" in this pa
1e000 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e ragraph..**.** ^
1e010 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 When [sqlite3_pr
1e020 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 epare_v2()] is u
1e030 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 sed to prepare a
1e040 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a statement, the.
1e050 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 ** statement mig
1e060 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 ht be re-prepare
1e070 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 d during [sqlite
1e080 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 3_step()] due to
1e090 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 a .** schema ch
1e0a0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 ange. Hence, th
1e0b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
1e0c0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 ould ensure that
1e0d0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 the.** correct
1e0e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1e0f0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 ack remains in p
1e100 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 lace during the
1e110 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1e120 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 ..**.** ^Note th
1e130 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 at the authorize
1e140 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
1e150 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e voked only durin
1e160 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 g.** [sqlite3_pr
1e170 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
1e180 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f variants. Autho
1e190 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a rization is not.
1e1a0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 ** performed dur
1e1b0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 ing statement ev
1e1c0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c aluation in [sql
1e1d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e ite3_step()], un
1e1e0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 less.** as state
1e1f0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 d in the previou
1e200 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c s paragraph, sql
1e210 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f ite3_step() invo
1e220 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 kes.** sqlite3_p
1e230 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 repare_v2() to r
1e240 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 eprepare a state
1e250 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 ment after a sch
1e260 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 ema change..*/.i
1e270 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 nt sqlite3_set_a
1e280 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c uthorizer(. sql
1e290 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 ite3*,. int (*x
1e2a0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c Auth)(void*,int,
1e2b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
1e2c0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
1e2d0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 ar*,const char*)
1e2e0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 ,. void *pUserD
1e2f0 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ata.);../*.** CA
1e300 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
1e310 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a er Return Codes.
1e320 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
1e330 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1e340 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 r | authorizer c
1e350 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1e360 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e ] must.** return
1e370 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
1e380 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 OK] or one of th
1e390 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 ese two constant
1e3a0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f s in order.** to
1e3b0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 signal SQLite w
1e3c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
1e3d0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d e action is perm
1e3e0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a itted. See the.
1e3f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f ** [sqlite3_set_
1e400 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
1e410 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 horizer document
1e420 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 ation] for addit
1e430 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ional.** informa
1e440 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 tion..**.** Note
1e450 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e that SQLITE_IGN
1e460 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 ORE is also used
1e470 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 as a [conflict
1e480 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d resolution mode]
1e490 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f .** returned fro
1e4a0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 m the [sqlite3_v
1e4b0 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 tab_on_conflict(
1e4c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f )] interface..*/
1e4d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1e4e0 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 DENY 1 /* Ab
1e4f0 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 ort the SQL stat
1e500 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 ement with an er
1e510 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
1e520 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 QLITE_IGNORE 2
1e530 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 /* Don't allow
1e540 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 access, but don'
1e550 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 t generate an er
1e560 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 ror */../*.** CA
1e570 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
1e580 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a er Action Codes.
1e590 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
1e5a0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1e5b0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 r()] interface r
1e5c0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 egisters a callb
1e5d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ack function.**
1e5e0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 that is invoked
1e5f0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 to authorize cer
1e600 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 tain SQL stateme
1e610 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 nt actions. The
1e620 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
1e630 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c eter to the call
1e640 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 back is an integ
1e650 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 er code that spe
1e660 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 cifies.** what a
1e670 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 ction is being a
1e680 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 uthorized. Thes
1e690 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 e are the intege
1e6a0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 r action codes t
1e6b0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f hat.** the autho
1e6c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d rizer callback m
1e6d0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a ay be passed..**
1e6e0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e .** These action
1e6f0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 code values sig
1e700 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f nify what kind o
1e710 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 f operation is t
1e720 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a o be.** authoriz
1e730 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 ed. The 3rd and
1e740 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 4th parameters
1e750 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 to the authoriza
1e760 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b tion.** callback
1e770 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 function will b
1e780 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 e parameters or
1e790 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f NULL depending o
1e7a0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 n which of these
1e7b0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 .** codes is use
1e7c0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
1e7d0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 parameter. ^(Th
1e7e0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
1e7f0 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 to the.** author
1e800 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
1e810 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1e820 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e database ("main
1e830 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 ", "temp",.** et
1e840 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c c.) if applicabl
1e850 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 e.)^ ^The 6th p
1e860 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1e870 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1e880 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ack.** is the na
1e890 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d me of the inner-
1e8a0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 most trigger or
1e8b0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 view that is res
1e8c0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 ponsible for.**
1e8d0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d the access attem
1e8e0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 pt or NULL if th
1e8f0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 is access attemp
1e900 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 t is directly fr
1e910 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 om.** top-level
1e920 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a SQL code..*/./**
1e930 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1e940 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1e950 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a ********* 3rd **
1e960 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a ********** 4th *
1e970 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 **********/.#def
1e980 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1e990 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 E_INDEX
1e9a0 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 1 /* Index Na
1e9b0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
1e9c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1e9d0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1e9e0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
1e9f0 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 2 /* Table Nam
1ea00 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1ea10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1ea20 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1ea30 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 TEMP_INDEX 3
1ea40 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
1ea50 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
1ea60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1ea70 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
1ea80 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 EMP_TABLE 4
1ea90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1eaa0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1eab0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1eac0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
1ead0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 MP_TRIGGER 5
1eae0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
1eaf0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1eb00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1eb10 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
1eb20 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 P_VIEW 6
1eb30 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
1eb40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1eb50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1eb60 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 LITE_CREATE_TRIG
1eb70 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f GER 7 /
1eb80 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
1eb90 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1eba0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1ebb0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 ITE_CREATE_VIEW
1ebc0 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 8 /*
1ebd0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
1ebe0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1ebf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1ec00 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 TE_DELETE
1ec10 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 9 /*
1ec20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1ec30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1ec40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1ec50 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 E_DROP_INDEX
1ec60 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 10 /* I
1ec70 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
1ec80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1ec90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1eca0 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 _DROP_TABLE
1ecb0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 11 /* Ta
1ecc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
1ecd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1ece0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ecf0 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 DROP_TEMP_INDEX
1ed00 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 12 /* Ind
1ed10 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
1ed20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1ed30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1ed40 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 ROP_TEMP_TABLE
1ed50 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 13 /* Tabl
1ed60 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1ed70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1ed80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1ed90 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 OP_TEMP_TRIGGER
1eda0 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 14 /* Trigg
1edb0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
1edc0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1edd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1ede0 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 P_TEMP_VIEW
1edf0 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 15 /* View N
1ee00 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
1ee10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1ee20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1ee30 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 _TRIGGER
1ee40 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 16 /* Trigger
1ee50 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
1ee60 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1ee70 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1ee80 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 VIEW
1ee90 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 17 /* View Nam
1eea0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
1eeb0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1eec0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 ne SQLITE_INSERT
1eed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
1eee0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 8 /* Table Nam
1eef0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1ef00 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1ef10 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 e SQLITE_PRAGMA
1ef20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 19
1ef30 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d /* Pragma Nam
1ef40 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 e 1st arg or
1ef50 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 NULL */.#define
1ef60 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 SQLITE_READ
1ef70 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20
1ef80 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1ef90 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 Column Name
1efa0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1efb0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 SQLITE_SELECT
1efc0 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 21
1efd0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
1efe0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1eff0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1f000 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f QLITE_TRANSACTIO
1f010 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 N 22
1f020 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 /* Operation
1f030 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1f040 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1f050 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 LITE_UPDATE
1f060 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 23 /
1f070 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1f080 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
1f090 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1f0a0 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 ITE_ATTACH
1f0b0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 24 /*
1f0c0 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 Filename
1f0d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1f0e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1f0f0 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 TE_DETACH
1f100 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 25 /*
1f110 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
1f120 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1f130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1f140 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 E_ALTER_TABLE
1f150 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 26 /* D
1f160 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 atabase Name T
1f170 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1f180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f190 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 _REINDEX
1f1a0 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 27 /* In
1f1b0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 dex Name NU
1f1c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1f1d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f1e0 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 ANALYZE
1f1f0 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 28 /* Tab
1f200 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1f210 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1f220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1f230 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 REATE_VTABLE
1f240 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 29 /* Tabl
1f250 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
1f260 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
1f270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1f280 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 OP_VTABLE
1f290 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 30 /* Table
1f2a0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c Name Modul
1f2b0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 e Name */.#d
1f2c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e efine SQLITE_FUN
1f2d0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 CTION
1f2e0 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 31 /* NULL
1f2f0 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 Functi
1f300 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 on Name */.#de
1f310 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 fine SQLITE_SAVE
1f320 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 POINT
1f330 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 32 /* Operati
1f340 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 on Savepoi
1f350 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 nt Name */.#def
1f360 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 ine SQLITE_COPY
1f370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1f380 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 0 /* No longe
1f390 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e r used */.#defin
1f3a0 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 e SQLITE_RECURSI
1f3b0 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 VE 33
1f3c0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
1f3d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1f3e0 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 */../*.**
1f3f0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e CAPI3REF: Tracin
1f400 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 g And Profiling
1f410 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
1f420 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
1f430 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b egister callback
1f440 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
1f450 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a can be used for.
1f460 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 ** tracing and p
1f470 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 rofiling the exe
1f480 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 cution of SQL st
1f490 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
1f4a0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
1f4b0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
1f4c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 d by sqlite3_tra
1f4d0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ce() is invoked
1f4e0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 at.** various ti
1f4f0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 mes when an SQL
1f500 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 statement is bei
1f510 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 ng run by [sqlit
1f520 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e e3_step()]..** ^
1f530 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 The sqlite3_trac
1f540 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 e() callback is
1f550 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 invoked with a U
1f560 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f TF-8 rendering o
1f570 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 f the.** SQL sta
1f580 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 tement text as t
1f590 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 he statement fir
1f5a0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 st begins execut
1f5b0 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 ing..** ^(Additi
1f5c0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 onal sqlite3_tra
1f5d0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d ce() callbacks m
1f5e0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 ight occur.** as
1f5f0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 each triggered
1f600 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e subprogram is en
1f610 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c tered. The call
1f620 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 backs for trigge
1f630 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 rs.** contain a
1f640 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e UTF-8 SQL commen
1f650 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 t that identifie
1f660 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e s the trigger.)^
1f670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
1f680 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 TE_TRACE_SIZE_LI
1f690 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d MIT] compile-tim
1f6a0 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 e option can be
1f6b0 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a used to limit.**
1f6c0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b the length of [
1f6d0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d bound parameter]
1f6e0 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 expansion in th
1f6f0 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 e output of sqli
1f700 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a te3_trace()..**.
1f710 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b ** ^The callback
1f720 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
1f730 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ered by sqlite3_
1f740 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 profile() is inv
1f750 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 oked.** as each
1f760 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 SQL statement fi
1f770 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 nishes. ^The pr
1f780 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 ofile callback c
1f790 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f ontains.** the o
1f7a0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e riginal statemen
1f7b0 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 t text and an es
1f7c0 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 timate of wall-c
1f7d0 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 lock time.** of
1f7e0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 how long that st
1f7f0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 atement took to
1f800 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 run. ^The profi
1f810 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 le callback.** t
1f820 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 ime is in units
1f830 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 of nanoseconds,
1f840 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 however the curr
1f850 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ent implementati
1f860 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 on.** is only ca
1f870 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 pable of millise
1f880 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 cond resolution
1f890 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 so the six least
1f8a0 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 significant.**
1f8b0 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 digits in the ti
1f8c0 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 me are meaningle
1f8d0 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 ss. Future vers
1f8e0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a ions of SQLite.*
1f8f0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 * might provide
1f900 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 greater resoluti
1f910 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c on on the profil
1f920 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 er callback. Th
1f930 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f e.** sqlite3_pro
1f940 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 file() function
1f950 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 is considered ex
1f960 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
1f970 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 s.** subject to
1f980 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 change in future
1f990 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
1f9a0 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ite..*/.void *sq
1f9b0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 lite3_trace(sqli
1f9c0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 te3*, void(*xTra
1f9d0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 ce)(void*,const
1f9e0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a char*), void*);.
1f9f0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
1fa00 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 TAL void *sqlite
1fa10 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 3_profile(sqlite
1fa20 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 3*,. void(*xPr
1fa30 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e ofile)(void*,con
1fa40 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 st char*,sqlite3
1fa50 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 _uint64), void*)
1fa60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1fa70 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 F: Query Progres
1fa80 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a s Callbacks.**.*
1fa90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 * ^The sqlite3_p
1faa0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
1fab0 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 D,N,X,P) interfa
1fac0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 ce causes the ca
1fad0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
1fae0 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b on X to be invok
1faf0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 ed periodically
1fb00 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e during long runn
1fb10 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ing calls to.**
1fb20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
1fb30 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
1fb40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1fb50 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 get_table()] for
1fb60 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
1fb70 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 nection D. An e
1fb80 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 xample use for t
1fb90 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 his.** interface
1fba0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 is to keep a GU
1fbb0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 I updated during
1fbc0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a a large query..
1fbd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d **.** ^The param
1fbe0 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 eter P is passed
1fbf0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 through as the
1fc00 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 only parameter t
1fc10 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 o the .** callba
1fc20 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 ck function X.
1fc30 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e ^The parameter N
1fc40 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d is the approxim
1fc50 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a ate number of .*
1fc60 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 * [virtual machi
1fc70 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d ne instructions]
1fc80 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 that are evalua
1fc90 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 ted between succ
1fca0 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 essive.** invoca
1fcb0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c tions of the cal
1fcc0 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 lback X. ^If N
1fcd0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 is less than one
1fce0 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 then the progre
1fcf0 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 ss.** handler is
1fd00 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a disabled..**.**
1fd10 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 ^Only a single
1fd20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
1fd30 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 may be defined
1fd40 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a at one time per.
1fd50 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1fd60 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e nection]; settin
1fd70 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 g a new progress
1fd80 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 handler cancels
1fd90 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e the.** old one.
1fda0 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d ^Setting param
1fdb0 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 eter X to NULL d
1fdc0 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 isables the prog
1fdd0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a ress handler..**
1fde0 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 ^The progress h
1fdf0 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 andler is also d
1fe00 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 isabled by setti
1fe10 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 ng N to a value
1fe20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a less.** than 1..
1fe30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 **.** ^If the pr
1fe40 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
1fe50 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
1fe60 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 , the operation
1fe70 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 is.** interrupte
1fe80 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 d. This feature
1fe90 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
1fea0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 implement a.** "
1feb0 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f Cancel" button o
1fec0 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 n a GUI progress
1fed0 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a dialog box..**.
1fee0 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 ** The progress
1fef0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
1ff00 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
1ff10 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
1ff20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
1ff30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1ff40 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
1ff50 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
1ff60 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ler..** Note tha
1ff70 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
1ff80 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
1ff90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
1ffa0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
1ffb0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
1ffc0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
1ffd0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
1ffe0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
1fff0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 graph..**.*/.voi
20000 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 d sqlite3_progre
20010 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 ss_handler(sqlit
20020 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 e3*, int, int(*)
20030 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b (void*), void*);
20040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20050 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 : Opening A New
20060 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
20070 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ion.**.** ^These
20080 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 routines open a
20090 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 n SQLite databas
200a0 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 e file as specif
200b0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 ied by the .** f
200c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
200d0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 . ^The filename
200e0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 argument is inte
200f0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 rpreted as UTF-8
20100 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
20110 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
20120 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 e3_open_v2() and
20130 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 as UTF-16 in th
20140 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a e native byte.**
20150 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 order for sqlit
20160 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 e3_open16(). ^(A
20170 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
20180 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 ction] handle is
20190 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 usually.** retu
201a0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 rned in *ppDb, e
201b0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 ven if an error
201c0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c occurs. The onl
201d0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 y exception is t
201e0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 hat.** if SQLite
201f0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
20200 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f locate memory to
20210 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 hold the [sqlit
20220 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 e3] object,.** a
20230 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 NULL will be wr
20240 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 itten into *ppDb
20250 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f instead of a po
20260 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
20270 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 lite3].** object
20280 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 .)^ ^(If the dat
20290 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
202a0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 (and/or created)
202b0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 successfully, t
202c0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f hen.** [SQLITE_O
202d0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 K] is returned.
202e0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 Otherwise an [e
202f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
20300 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a turned.)^ ^The.*
20310 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
20320 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 g()] or [sqlite3
20330 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 _errmsg16()] rou
20340 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 tines can be use
20350 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 d to obtain.** a
20360 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 n English langua
20370 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f ge description o
20380 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c f the error foll
20390 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 owing a failure
203a0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
203b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
203c0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
203d0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 ^The default enc
203e0 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 oding for the da
203f0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 tabase will be U
20400 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 TF-8 if.** sqlit
20410 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
20420 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
20430 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 s called and.**
20440 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
20450 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
20460 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 if sqlite3_open1
20470 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 6() is used..**.
20480 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f ** Whether or no
20490 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 t an error occur
204a0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 s when it is ope
204b0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a ned, resources.*
204c0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
204d0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
204e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
204f0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c le should be rel
20500 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 eased by.** pass
20510 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
20520 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e e3_close()] when
20530 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 it is no longer
20540 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
20550 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 The sqlite3_ope
20560 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 n_v2() interface
20570 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
20580 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 te3_open().** ex
20590 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 cept that it acc
205a0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f epts two additio
205b0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 nal parameters f
205c0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f or additional co
205d0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 ntrol.** over th
205e0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
205f0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 onnection. ^(Th
20600 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
20610 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
20620 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 open_v2() can ta
20630 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 ke one of.** the
20640 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 following three
20650 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 values, optiona
20660 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 lly combined wit
20670 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 h the .** [SQLIT
20680 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c E_OPEN_NOMUTEX],
20690 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 [SQLITE_OPEN_FU
206a0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 LLMUTEX], [SQLIT
206b0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
206c0 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f HE],.** [SQLITE_
206d0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
206e0 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 E], and/or [SQLI
206f0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
20700 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e gs:)^.**.** <dl>
20710 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
20720 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
20730 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
20740 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
20750 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 ned in read-only
20760 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 mode. If the d
20770 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 atabase does not
20780 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 .** already exis
20790 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
207a0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
207b0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c **.** ^(<dt>[SQL
207c0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
207d0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
207e0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
207f0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
20800 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 ng and writing i
20810 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 f possible, or r
20820 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 eading.** only i
20830 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 f the file is wr
20840 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
20850 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
20860 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 ystem. In eithe
20870 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 r.** case the da
20880 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 tabase must alre
20890 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 ady exist, other
208a0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 wise an error is
208b0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
208c0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
208d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
208e0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
208f0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 OPEN_CREATE]</dt
20900 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
20910 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
20920 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
20930 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 writing, and is
20940 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 created if.** it
20950 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 does not alread
20960 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 y exist. This is
20970 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 the behavior th
20980 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 at is always use
20990 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 d for.** sqlite3
209a0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
209b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 te3_open16().</d
209c0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a d>)^.** </dl>.**
209d0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
209e0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
209f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
20a00 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
20a10 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 ** combinations
20a20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 shown above opti
20a30 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
20a40 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 with other.** [S
20a50 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
20a60 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 NLY | SQLITE_OPE
20a70 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 N_* bits].** the
20a80 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
20a90 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
20aa0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 ** ^If the [SQLI
20ab0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
20ac0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 flag is set, th
20ad0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
20ae0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 connection.** op
20af0 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 ens in the multi
20b00 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
20b10 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 ng mode] as long
20b20 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 as the single-t
20b30 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 hread.** mode ha
20b40 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 s not been set a
20b50 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
20b60 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e r start-time. ^
20b70 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
20b80 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
20b90 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 ] flag is set th
20ba0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
20bb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 connection opens
20bc0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 .** in the seria
20bd0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
20be0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 mode] unless si
20bf0 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a ngle-thread was.
20c00 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
20c10 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c lected at compil
20c20 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d e-time or start-
20c30 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 time..** ^The [S
20c40 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
20c50 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 DCACHE] flag cau
20c60 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ses the database
20c70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 connection to b
20c80 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f e.** eligible to
20c90 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 use [shared cac
20ca0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 he mode], regard
20cb0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
20cc0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a or not shared.**
20cd0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 cache is enable
20ce0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
20cf0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
20d00 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a ache()]. ^The.*
20d10 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 * [SQLITE_OPEN_P
20d20 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 RIVATECACHE] fla
20d30 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
20d40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
20d50 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 to not.** parti
20d60 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 cipate in [share
20d70 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 d cache mode] ev
20d80 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 en if it is enab
20d90 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 led..**.** ^The
20da0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
20db0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
20dc0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d _v2() is the nam
20dd0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c e of the.** [sql
20de0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
20df0 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 that defines th
20e00 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
20e10 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
20e20 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 t.** the new dat
20e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
20e40 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 should use. ^I
20e50 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
20e60 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e ameter is.** a N
20e70 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
20e80 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
20e90 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
20ea0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a t is used..**.**
20eb0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d ^If the filenam
20ec0 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c e is ":memory:",
20ed0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
20ee0 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 temporary in-me
20ef0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a mory database.**
20f00 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 is created for
20f10 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 the connection.
20f20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 ^This in-memory
20f30 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 database will v
20f40 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 anish when.** th
20f50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
20f60 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
20f70 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
20f80 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
20f90 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 t.** make use of
20fa0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 additional spec
20fb0 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 ial filenames th
20fc0 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 at begin with th
20fd0 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e e ":" character.
20fe0 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d .** It is recomm
20ff0 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 ended that when
21000 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e a database filen
21010 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 ame actually doe
21020 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 s begin with.**
21030 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 a ":" character
21040 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 you should prefi
21050 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 x the filename w
21060 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 ith a pathname s
21070 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 uch as.** "./" t
21080 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 o avoid ambiguit
21090 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 y..**.** ^If the
210a0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 filename is an
210b0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 empty string, th
210c0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
210d0 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 mporary.** on-di
210e0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c sk database will
210f0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 be created. ^T
21100 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 his private data
21110 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 base will be.**
21120 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 automatically de
21130 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 leted as soon as
21140 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
21150 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
21160 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 ed..**.** [[URI
21170 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c filenames in sql
21180 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 ite3_open()]] <h
21190 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 3>URI Filenames<
211a0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b /h3>.**.** ^If [
211b0 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e URI filename] in
211c0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
211d0 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 enabled, and the
211e0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
211f0 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 nt.** begins wit
21200 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 h "file:", then
21210 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
21220 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
21230 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 URI. ^URI.** fi
21240 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 lename interpret
21250 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ation is enabled
21260 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
21270 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 OPEN_URI] flag i
21280 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 s.** set in the
21290 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
212a0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
212b0 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 v2(), or if it h
212c0 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c as.** been enabl
212d0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e ed globally usin
212e0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
212f0 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e NFIG_URI] option
21300 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 with the.** [sq
21310 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
21320 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 method or by the
21330 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 [SQLITE_USE_URI
21340 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
21350 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 ption..** As of
21360 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
21370 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 .7.7, URI filena
21380 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f me interpretatio
21390 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a n is turned off.
213a0 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 ** by default, b
213b0 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 ut future releas
213c0 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 es of SQLite mig
213d0 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 ht enable URI fi
213e0 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 lename.** interp
213f0 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 retation by defa
21400 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 ult. See "[URI
21410 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 filenames]" for
21420 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
21430 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
21440 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 URI filenames a
21450 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 re parsed accord
21460 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e ing to RFC 3986.
21470 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e ^If the URI con
21480 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 tains an.** auth
21490 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d ority, then it m
214a0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e ust be either an
214b0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 empty string or
214c0 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 the string .**
214d0 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 "localhost". ^If
214e0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 the authority i
214f0 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 s not an empty s
21500 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 tring or "localh
21510 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 ost", an .** err
21520 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 or is returned t
21530 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 o the caller. ^T
21540 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 he fragment comp
21550 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 onent of a URI,
21560 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 if .** present,
21570 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a is ignored..**.*
21580 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 * ^SQLite uses t
21590 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e he path componen
215a0 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 t of the URI as
215b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
215c0 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 disk file.** whi
215d0 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 ch contains the
215e0 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 database. ^If th
215f0 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 e path begins wi
21600 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 th a '/' charact
21610 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 er, .** then it
21620 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
21630 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 s an absolute pa
21640 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 th. ^If the path
21650 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 does not begin
21660 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 .** with a '/' (
21670 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 meaning that the
21680 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 authority secti
21690 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 on is omitted fr
216a0 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 om the URI).** t
216b0 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 hen the path is
216c0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
216d0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 relative path.
216e0 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c .** ^On windows,
216f0 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f the first compo
21700 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c nent of an absol
21710 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 ute path .** is
21720 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 a drive specific
21730 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 ation (e.g. "C:"
21740 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 )..**.** [[core
21750 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 URI query parame
21760 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 ters]].** The qu
21770 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 ery component of
21780 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 a URI may conta
21790 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 in parameters th
217a0 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 at are interpret
217b0 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 ed.** either by
217c0 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f SQLite itself, o
217d0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 r by a [VFS | cu
217e0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 stom VFS impleme
217f0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c ntation]..** SQL
21800 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 ite interprets t
21810 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 he following thr
21820 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 ee query paramet
21830 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ers:.**.** <ul>.
21840 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 ** <li> <b>vfs
21850 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 </b>: ^The "vfs"
21860 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
21870 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 e used to specif
21880 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a y the name of.**
21890 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 a VFS objec
218a0 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 t that provides
218b0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
218c0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
218d0 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 hat should.**
218e0 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 be used to acc
218f0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ess the database
21900 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e file on disk. ^
21910 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 If this option i
21920 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 s set to.**
21930 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 an empty string
21940 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 the default VFS
21950 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 object is used.
21960 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 ^Specifying an u
21970 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 nknown.** VF
21980 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e S is an error. ^
21990 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f If sqlite3_open_
219a0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 v2() is used and
219b0 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 the vfs option
219c0 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e is.** presen
219d0 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 t, then the VFS
219e0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
219f0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 option takes pr
21a00 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a ecedence over.**
21a10 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 the value p
21a20 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 assed as the fou
21a30 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
21a40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
21a50 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e ()..**.** <li>
21a60 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 <b>mode</b>: ^(
21a70 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 The mode paramet
21a80 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f er may be set to
21a90 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 either "ro", "r
21aa0 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 w",.** "rwc"
21ab0 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 , or "memory". A
21ac0 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 ttempting to set
21ad0 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 it to any other
21ae0 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 value is.**
21af0 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a an error)^. .**
21b00 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 ^If "ro" is
21b10 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e specified, then
21b20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
21b30 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
21b40 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 -only .** ac
21b50 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 cess, just as if
21b60 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
21b70 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 N_READONLY] flag
21b80 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e had been set in
21b90 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 the .** thi
21ba0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
21bb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
21bc0 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f . ^If the mode o
21bd0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 ption is set to
21be0 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 .** "rw", th
21bf0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
21c00 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
21c10 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f ad-write (but no
21c20 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 t create) .**
21c30 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 access, as if
21c40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
21c50 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 WRITE (but not S
21c60 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
21c70 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 E) had .** b
21c80 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 een set. ^Value
21c90 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c "rwc" is equival
21ca0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 ent to setting b
21cb0 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 oth .** SQLI
21cc0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
21cd0 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 E and SQLITE_OPE
21ce0 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 N_CREATE. ^If t
21cf0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 he mode option i
21d00 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 s.** set to
21d10 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 "memory" then a
21d20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 pure [in-memory
21d30 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e database] that n
21d40 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 ever reads.**
21d50 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d or writes from
21d60 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e disk is used. ^
21d70 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 It is an error t
21d80 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 o specify a valu
21d90 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 e for.** the
21da0 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 mode parameter
21db0 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 that is less res
21dc0 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 trictive than th
21dd0 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a at specified by.
21de0 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 ** the flags
21df0 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 passed in the t
21e00 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
21e10 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
21e20 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 2()..**.** <li
21e30 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 > <b>cache</b>:
21e40 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d ^The cache param
21e50 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 eter may be set
21e60 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 to either "share
21e70 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 d" or.** "pr
21e80 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 ivate". ^Setting
21e90 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 it to "shared"
21ea0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f is equivalent to
21eb0 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 setting the.**
21ec0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f SQLITE_OPEN_
21ed0 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 SHAREDCACHE bit
21ee0 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 in the flags arg
21ef0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a ument passed to.
21f00 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f ** sqlite3_o
21f10 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 pen_v2(). ^Setti
21f20 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 ng the cache par
21f30 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 ameter to "priva
21f40 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 te" is .** e
21f50 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
21f60 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f ting the SQLITE_
21f70 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
21f80 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 E bit..** ^I
21f90 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 f sqlite3_open_v
21fa0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 2() is used and
21fb0 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 the "cache" para
21fc0 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 meter is present
21fd0 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 in.** a URI
21fe0 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 filename, its v
21ff0 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 alue overrides a
22000 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 ny behavior requ
22010 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 ested by setting
22020 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f .** SQLITE_O
22030 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
22040 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f or SQLITE_OPEN_
22050 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 SHAREDCACHE flag
22060 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 ..**.** <li> <b
22070 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 >psow</b>: ^The
22080 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 6d psow parameter m
22090 61 79 20 62 65 20 22 74 72 75 65 22 20 28 6f 72 ay be "true" (or
220a0 20 22 6f 6e 22 20 6f 72 20 22 79 65 73 22 20 6f "on" or "yes" o
220b0 72 0a 2a 2a 20 20 20 20 20 22 31 22 29 20 6f 72 r.** "1") or
220c0 20 22 66 61 6c 73 65 22 20 28 6f 72 20 22 6f 66 "false" (or "of
220d0 66 22 20 6f 72 20 22 6e 6f 22 20 6f 72 20 22 30 f" or "no" or "0
220e0 22 29 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ") to indicate t
220f0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b hat the.** [
22100 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 powersafe overwr
22110 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f ite] property do
22120 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 es or does not a
22130 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 pply to the.**
22140 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 storage media
22150 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 on which the da
22160 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 tabase file resi
22170 64 65 73 2e 20 20 5e 54 68 65 20 70 73 6f 77 20 des. ^The psow
22180 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 query.** par
22190 61 6d 65 74 65 72 20 6f 6e 6c 79 20 77 6f 72 6b ameter only work
221a0 73 20 66 6f 72 20 74 68 65 20 62 75 69 6c 74 2d s for the built-
221b0 69 6e 20 75 6e 69 78 20 61 6e 64 20 57 69 6e 64 in unix and Wind
221c0 6f 77 73 20 56 46 53 65 73 2e 0a 2a 2a 0a 2a 2a ows VFSes..**.**
221d0 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b <li> <b>nolock
221e0 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 </b>: ^The noloc
221f0 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 k parameter is a
22200 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 boolean query p
22210 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 arameter.**
22220 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 which if set dis
22230 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 ables file locki
22240 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a ng in rollback j
22250 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 ournal modes. T
22260 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 his.** is us
22270 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 eful for accessi
22280 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e ng a database on
22290 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 a filesystem th
222a0 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 at does not.**
222b0 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 support locki
222c0 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 ng. Caution: D
222d0 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 atabase corrupti
222e0 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 on might result
222f0 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 if two.** or
22300 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 more processes
22310 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d write to the sam
22320 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 e database and a
22330 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a ny one of those.
22340 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 ** processes
22350 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a uses nolock=1..
22360 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 **.** <li> <b>i
22370 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 mmutable</b>: ^T
22380 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 he immutable par
22390 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c ameter is a bool
223a0 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 ean query.**
223b0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 parameter that
223c0 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 indicates that t
223d0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
223e0 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a is stored on.**
223f0 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d read-only m
22400 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d edia. ^When imm
22410 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 utable is set, S
22420 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
22430 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 at the.** da
22440 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e tabase file cann
22450 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 ot be changed, e
22460 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 ven by a process
22470 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 with higher.**
22480 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 privilege, a
22490 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 nd so the databa
224a0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 se is opened rea
224b0 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c d-only and all l
224c0 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e ocking.** an
224d0 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 d change detecti
224e0 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 on is disabled.
224f0 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e Caution: Settin
22500 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a g the immutable.
22510 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 ** property
22520 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 on a database fi
22530 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 le that does in
22540 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 fact change can
22550 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e result.** in
22560 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 incorrect query
22570 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 results and/or
22580 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d [SQLITE_CORRUPT]
22590 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 errors..**
225a0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 See also: [SQLIT
225b0 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c E_IOCAP_IMMUTABL
225c0 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a E]..** .**
225d0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 </ul>.**.** ^Sp
225e0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e ecifying an unkn
225f0 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e own parameter in
22600 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f the query compo
22610 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 nent of a URI is
22620 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 not an.** error
22630 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
22640 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 ns of SQLite mig
22650 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 ht understand ad
22660 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a ditional query.*
22670 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 * parameters. S
22680 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d ee "[query param
22690 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 eters with speci
226a0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 al meaning to SQ
226b0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 Lite]" for.** ad
226c0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
226d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 tion..**.** [[UR
226e0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 I filename examp
226f0 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 les]] <h3>URI fi
22700 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c lename examples<
22710 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c /h3>.**.** <tabl
22720 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 e border="1" ali
22730 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 gn=center cellpa
22740 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e dding=5>.** <tr>
22750 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d <th> URI filenam
22760 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a es <th> Results.
22770 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
22780 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a :data.db <td> .*
22790 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 * Open
227a0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 the file "data.d
227b0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e b" in the curren
227c0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 t directory..**
227d0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 <tr><td> file:/h
227e0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
227f0 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 <br>.**
22800 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 file:///home/fr
22810 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 ed/data.db <br>
22820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
22830 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f e://localhost/ho
22840 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 me/fred/data.db
22850 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 <br> <td> .**
22860 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 Open the
22870 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f database file "/
22880 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
22890 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 b"..** <tr><td>
228a0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f file://darkstar/
228b0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
228c0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 b <td> .**
228d0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 An error. "d
228e0 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 arkstar" is not
228f0 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 a recognized aut
22900 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c hority..** <tr><
22910 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d td style="white-
22920 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a space:nowrap"> .
22930 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 ** file
22940 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 :///C:/Documents
22950 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 %20and%20Setting
22960 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 s/fred/Desktop/d
22970 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 ata.db.** <t
22980 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a d> Windows only:
22990 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 Open the file "
229a0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 data.db" on fred
229b0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 's desktop on dr
229c0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ive.**
229d0 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 C:. Note that th
229e0 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 e %20 escaping i
229f0 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 n this example i
22a00 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a s not strictly .
22a10 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 ** nece
22a20 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 ssary - space ch
22a30 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 aracters can be
22a40 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a used literally.*
22a50 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 * in UR
22a60 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 I filenames..**
22a70 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
22a80 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 ta.db?mode=ro&ca
22a90 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e che=private <td>
22aa0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
22ab0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 en file "data.db
22ac0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 " in the current
22ad0 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 directory for r
22ae0 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e ead-only access.
22af0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 .** Reg
22b00 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
22b10 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 er or not shared
22b20 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 -cache mode is e
22b30 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 nabled by.**
22b40 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 default, u
22b50 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 se a private cac
22b60 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 he..** <tr><td>
22b70 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f file:/home/fred/
22b80 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 data.db?vfs=unix
22b90 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a -dotfile <td>.**
22ba0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 Open f
22bb0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f ile "/home/fred/
22bc0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 data.db". Use th
22bd0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 e special VFS "u
22be0 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 nix-dotfile".**
22bf0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 that us
22c00 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 es dot-files in
22c10 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 place of posix a
22c20 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e dvisory locking.
22c30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
22c40 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 e:data.db?mode=r
22c50 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a eadonly <td> .**
22c60 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 An err
22c70 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 or. "readonly" i
22c80 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 s not a valid op
22c90 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f tion for the "mo
22ca0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a de" parameter..*
22cb0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a * </table>.**.**
22cc0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 ^URI hexadecima
22cd0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 l escape sequenc
22ce0 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 es (%HH) are sup
22cf0 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 ported within th
22d00 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 e path and.** qu
22d10 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f ery components o
22d20 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 f a URI. A hexad
22d30 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
22d40 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 quence consists
22d50 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 of a.** percent
22d60 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c sign - "%" - fol
22d70 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 lowed by exactly
22d80 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c two hexadecimal
22d90 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 digits .** spec
22da0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 ifying an octet
22db0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 value. ^Before t
22dc0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 he path or query
22dd0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 components of a
22de0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 .** URI filename
22df0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
22e00 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 , they are encod
22e10 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 ed using UTF-8 a
22e20 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 nd all .** hexad
22e30 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
22e40 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 quences replaced
22e50 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 by a single byt
22e60 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
22e70 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e .** correspondin
22e80 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 g octet. If this
22e90 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 process generat
22ea0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 es an invalid UT
22eb0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a F-8 encoding,.**
22ec0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
22ed0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
22ee0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
22ef0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 dows users:</b>
22f00 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 The encoding us
22f10 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e ed for the filen
22f20 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ame argument.**
22f30 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 of sqlite3_open(
22f40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
22f50 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 en_v2() must be
22f60 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 UTF-8, not whate
22f70 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 ver.** codepage
22f80 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 is currently def
22f90 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 ined. Filenames
22fa0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 containing inte
22fb0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 rnational.** cha
22fc0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 racters must be
22fd0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 converted to UTF
22fe0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 -8 prior to pass
22ff0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a ing them into.**
23000 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
23010 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
23020 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e v2()..**.** <b>N
23030 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 ote to Windows R
23040 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 untime users:</b
23050 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 > The temporary
23060 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 directory must
23070 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 be set.** prior
23080 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 to calling sqlit
23090 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
230a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 ite3_open_v2().
230b0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 Otherwise, vari
230c0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 ous.** features
230d0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 that require the
230e0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 use of temporar
230f0 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c y files may fail
23100 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
23110 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f : [sqlite3_temp_
23120 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e directory].*/.in
23130 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a t sqlite3_open(.
23140 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
23150 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
23160 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
23170 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
23180 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
23190 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
231a0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
231b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
231c0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 pen16(. const v
231d0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 oid *filename,
231e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
231f0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a ename (UTF-16) *
23200 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
23210 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
23220 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
23230 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 ndle */.);.int s
23240 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a qlite3_open_v2(.
23250 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
23260 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
23270 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
23280 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
23290 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 te3 **ppDb,
232a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
232b0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
232c0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 int flags,
232d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 /* Fla
232e0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 gs */. const ch
232f0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 ar *zVfs
23300 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d /* Name of VFS m
23310 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a odule to use */.
23320 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
23330 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 EF: Obtain Value
23340 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 s For URI Parame
23350 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ters.**.** These
23360 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 are utility rou
23370 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f tines, useful to
23380 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
23390 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b ions, that check
233a0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 .** to see if a
233b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 database file wa
233c0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e s a URI that con
233d0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 tained a specifi
233e0 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 c query .** para
233f0 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f meter, and if so
23400 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c obtains the val
23410 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 ue of that query
23420 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
23430 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 * If F is the da
23440 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
23450 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 pointer passed i
23460 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 nto the xOpen()
23470 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 method of .** a
23480 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
23490 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 on when the flag
234a0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 s parameter to x
234b0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f Open() has one o
234c0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 r .** more of th
234d0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 e [SQLITE_OPEN_U
234e0 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f RI] or [SQLITE_O
234f0 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 PEN_MAIN_DB] bit
23500 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 s set and.** P i
23510 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
23520 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 e query paramete
23530 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 r, then.** sqlit
23540 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
23550 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 (F,P) returns th
23560 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 e value of the P
23570 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 .** parameter if
23580 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 it exists or a
23590 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 NULL pointer if
235a0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 P does not appea
235b0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 r as a .** query
235c0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e parameter on F.
235d0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 If P is a quer
235e0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 y parameter of F
235f0 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 .** has no expli
23600 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 cit value, then
23610 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
23620 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
23630 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ns.** a pointer
23640 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 to an empty stri
23650 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ng..**.** The sq
23660 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
23670 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
23680 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 assumes that P
23690 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 is a boolean.**
236a0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
236b0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f turns true (1) o
236c0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f r false (0) acco
236d0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c rding to the val
236e0 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 ue.** of P. The
236f0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
23700 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
23710 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ine returns true
23720 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 (1) if the.** v
23730 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 alue of query pa
23740 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 rameter P is one
23750 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 of "yes", "true
23760 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e ", or "on" in an
23770 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 y.** case or if
23780 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 the value begins
23790 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f with a non-zero
237a0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a number. The .*
237b0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f * sqlite3_uri_bo
237c0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 olean(F,P,B) rou
237d0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 tines returns fa
237e0 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 lse (0) if the v
237f0 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 alue of.** query
23800 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 parameter P is
23810 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 one of "no", "fa
23820 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 lse", or "off" i
23830 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a n any case or.**
23840 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 if the value be
23850 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 gins with a nume
23860 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 ric zero. If P
23870 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a is not a query.*
23880 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 * parameter on F
23890 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 or if the value
238a0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f of P is does no
238b0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 t match any of t
238c0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 he.** above, the
238d0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f n sqlite3_uri_bo
238e0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 olean(F,P,B) ret
238f0 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a urns (B!=0)..**.
23900 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
23910 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 ri_int64(F,P,D)
23920 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 routine converts
23930 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
23940 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 into a.** 64-bit
23950 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 signed integer
23960 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 and returns that
23970 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 integer, or D i
23980 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 f P does not.**
23990 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 exist. If the v
239a0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d alue of P is som
239b0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
239c0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 n an integer, th
239d0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 en.** zero is re
239e0 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 turned..** .** I
239f0 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f F is a NULL po
23a00 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 inter, then sqli
23a10 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
23a20 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e r(F,P) returns N
23a30 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 ULL and.** sqlit
23a40 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
23a50 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e ,P,B) returns B.
23a60 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 If F is not a
23a70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 NULL pointer and
23a80 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 .** is not a dat
23a90 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e abase file pathn
23aa0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ame pointer that
23ab0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 SQLite passed i
23ac0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a nto the xOpen.**
23ad0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 VFS method, the
23ae0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f n the behavior o
23af0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 f this routine i
23b00 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
23b10 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 probably.** unde
23b20 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 sirable..*/.cons
23b30 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
23b40 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f uri_parameter(co
23b50 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
23b60 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ame, const char
23b70 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 *zParam);.int sq
23b80 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
23b90 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 n(const char *zF
23ba0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ile, const char
23bb0 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 *zParam, int bDe
23bc0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f fault);.sqlite3_
23bd0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 int64 sqlite3_ur
23be0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 i_int64(const ch
23bf0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a ar*, const char*
23c00 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
23c10 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
23c20 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 EF: Error Codes
23c30 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a And Messages.**.
23c40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
23c50 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 errcode() interf
23c60 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
23c70 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 numeric [result
23c80 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 code] or.** [ext
23c90 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
23ca0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 e] for the most
23cb0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 recent failed sq
23cc0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c lite3_* API call
23cd0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
23ce0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
23cf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 connection]. If
23d00 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c a prior API call
23d10 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 failed.** but t
23d20 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 he most recent A
23d30 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 PI call succeede
23d40 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 d, the return va
23d50 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 lue from.** sqli
23d60 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 te3_errcode() is
23d70 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 undefined. ^Th
23d80 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
23d90 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 ed_errcode().**
23da0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 interface is the
23db0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 same except tha
23dc0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 t it always retu
23dd0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 rns the .** [ext
23de0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
23df0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 e] even when ext
23e00 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
23e10 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c es are.** disabl
23e20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
23e30 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
23e40 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
23e50 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
23e60 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a glish-language.*
23e70 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
23e80 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
23e90 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
23ea0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 or UTF-16 respe
23eb0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 ctively..** ^(Me
23ec0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
23ed0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
23ee0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 tring is managed
23ef0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 internally..**
23f00 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
23f10 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
23f20 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 worry about fre
23f30 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e eing the result.
23f40 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
23f50 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 error string mi
23f60 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 ght be overwritt
23f70 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 en or deallocate
23f80 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 d by.** subseque
23f90 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 nt calls to othe
23fa0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
23fb0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a ce functions.)^.
23fc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
23fd0 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 e3_errstr() inte
23fe0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
23ff0 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 e English-langua
24000 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 ge text.** that
24010 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 describes the [r
24020 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 esult code], as
24030 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f UTF-8..** ^(Memo
24040 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
24050 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
24060 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
24070 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 nternally.** and
24080 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 must not be fre
24090 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
240a0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 ation)^..**.** W
240b0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a hen the serializ
240c0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
240d0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 de] is in use, i
240e0 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a t might be the.*
240f0 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 * case that a se
24100 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 cond error occur
24110 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 s on a separate
24120 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 thread in betwee
24130 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 n.** the time of
24140 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 the first error
24150 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f and the call to
24160 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
24170 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 s..** When that
24180 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 happens, the sec
24190 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 ond error will b
241a0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 e reported since
241b0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 these.** interf
241c0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f aces always repo
241d0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 rt the most rece
241e0 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 nt result. To a
241f0 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 void.** this, ea
24200 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 ch thread can ob
24210 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 tain exclusive u
24220 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 se of the [datab
24230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
24240 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 D.** by invoking
24250 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
24260 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f enter]([sqlite3_
24270 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 db_mutex](D)) be
24280 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a fore beginning.*
24290 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 * to use D and i
242a0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
242b0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 _mutex_leave]([s
242c0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
242d0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c (D)) after.** al
242e0 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 l calls to the i
242f0 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 nterfaces listed
24300 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 here are comple
24310 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ted..**.** If an
24320 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 interface fails
24330 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 with SQLITE_MIS
24340 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 USE, that means
24350 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a the interface.**
24360 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 was invoked inc
24370 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 orrectly by the
24380 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e application. In
24390 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a that case, the.
243a0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e ** error code an
243b0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 d message may or
243c0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e may not be set.
243d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
243e0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
243f0 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *db);.int sqlite
24400 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
24410 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
24420 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
24430 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 ite3_errmsg(sqli
24440 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 te3*);.const voi
24450 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d *sqlite3_errms
24460 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 g16(sqlite3*);.c
24470 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
24480 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a e3_errstr(int);.
24490 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
244a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f SQL Statement O
244b0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
244c0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 S: {prepared sta
244d0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 tement} {prepare
244e0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a d statements}.**
244f0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
24500 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
24510 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 epresents a sing
24520 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
24530 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
24540 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e is variously kn
24550 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 own as a "prepar
24560 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 ed statement" or
24570 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 a.** "compiled
24580 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f SQL statement" o
24590 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 r simply as a "s
245a0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a tatement"..**.**
245b0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 The life of a s
245c0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
245d0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c goes something l
245e0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
245f0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 <ol>.** <li> Cre
24600 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 ate the object u
24610 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
24620 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 epare_v2()] or a
24630 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 related.**
24640 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c function..** <l
24650 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 i> Bind values t
24660 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 o [host paramete
24670 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 rs] using the sq
24680 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a lite3_bind_*().*
24690 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 * interface
246a0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 s..** <li> Run t
246b0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e he SQL by callin
246c0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
246d0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 )] one or more t
246e0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 imes..** <li> Re
246f0 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e set the statemen
24700 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
24710 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 _reset()] then g
24720 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 o back.** t
24730 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 o step 2. Do th
24740 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 is zero or more
24750 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 times..** <li> D
24760 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 estroy the objec
24770 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
24780 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
24790 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 </ol>.**.** Ref
247a0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 er to documentat
247b0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 ion on individua
247c0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 l methods above
247d0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
247e0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
247f0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
24800 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 sqlite3_stmt sq
24810 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a lite3_stmt;../*.
24820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
24830 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a -time Limits.**.
24840 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 ** ^(This interf
24850 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 ace allows the s
24860 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 ize of various c
24870 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
24880 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 limited.** on a
24890 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f connection by co
248a0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 nnection basis.
248b0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
248c0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b eter is the.** [
248d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
248e0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 ion] whose limit
248f0 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 is to be set or
24900 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a queried. The.*
24910 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
24920 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 er is one of the
24930 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 [limit categori
24940 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 es] that define
24950 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f a.** class of co
24960 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 nstructs to be s
24970 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 ize limited. Th
24980 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
24990 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 r is the.** new
249a0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 limit for that c
249b0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a onstruct.)^.**.*
249c0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 * ^If the new li
249d0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
249e0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
249f0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
24a00 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 ..** ^(For each
24a10 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 limit category S
24a20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e QLITE_LIMIT_<i>N
24a30 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 AME</i> there is
24a40 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c a .** [limits |
24a50 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
24a60 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d d].** set at com
24a70 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 pile-time by a C
24a80 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
24a90 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c cro called.** [l
24aa0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d imits | SQLITE_M
24ab0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e AX_<i>NAME</i>].
24ac0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 .** (The "_LIMIT
24ad0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 _" in the name i
24ae0 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d s changed to "_M
24af0 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 AX_".))^.** ^Att
24b00 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 empts to increas
24b10 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 e a limit above
24b20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 its hard upper b
24b30 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 ound are.** sile
24b40 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 ntly truncated t
24b50 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 o the hard upper
24b60 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 bound..**.** ^R
24b70 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
24b80 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
24b90 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 limit was change
24ba0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 d, the .** [sqli
24bb0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 te3_limit()] int
24bc0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
24bd0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f he prior value o
24be0 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 f the limit..**
24bf0 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 ^Hence, to find
24c00 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
24c10 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 e of a limit wit
24c20 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 hout changing it
24c30 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f ,.** simply invo
24c40 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 ke this interfac
24c50 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 e with the third
24c60 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 parameter set t
24c70 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d o -1..**.** Run-
24c80 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 time limits are
24c90 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
24ca0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 in applications
24cb0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 that manage.**
24cc0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 both their own i
24cd0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
24ce0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 and also databa
24cf0 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e ses that are con
24d00 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e trolled.** by un
24d10 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c trusted external
24d20 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 sources. An ex
24d30 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f ample applicatio
24d40 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 n might be a.**
24d50 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 web browser that
24d60 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 has its own dat
24d70 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 abases for stori
24d80 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a ng history and.*
24d90 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 * separate datab
24da0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 ases controlled
24db0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 by JavaScript ap
24dc0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c plications downl
24dd0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 oaded.** off the
24de0 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 Internet. The
24df0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
24e00 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 es can be given
24e10 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 the.** large, de
24e20 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 fault limits. D
24e30 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 atabases managed
24e40 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 by external sou
24e50 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 rces can.** be g
24e60 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 iven much smalle
24e70 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 r limits designe
24e80 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 d to prevent a d
24e90 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 enial of service
24ea0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 .** attack. Dev
24eb0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c elopers might al
24ec0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 so want to use t
24ed0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
24ee0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a authorizer()].**
24ef0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 interface to fu
24f00 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e rther control un
24f10 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 trusted SQL. Th
24f20 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 e size of the da
24f30 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 tabase.** create
24f40 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 d by an untruste
24f50 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 d script can be
24f60 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 contained using
24f70 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 the.** [max_page
24f80 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
24f90 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d ..**.** New run-
24fa0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 time limit categ
24fb0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 ories may be add
24fc0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
24fd0 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 eases..*/.int sq
24fe0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 lite3_limit(sqli
24ff0 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e te3*, int id, in
25000 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a t newVal);../*.*
25010 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
25020 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 Time Limit Categ
25030 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ories.** KEYWORD
25040 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f S: {limit catego
25050 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 ry} {*limit cate
25060 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 gories}.**.** Th
25070 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ese constants de
25080 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 fine various per
25090 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a formance limits.
250a0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c ** that can be l
250b0 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 owered at run-ti
250c0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 me using [sqlite
250d0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 3_limit()]..** T
250e0 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 he synopsis of t
250f0 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
25100 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 he various limit
25110 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 s is shown below
25120 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
25130 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 information is a
25140 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d vailable at [lim
25150 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 its | Limits in
25160 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c SQLite]..**.** <
25170 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f dl>.** [[SQLITE_
25180 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e LIMIT_LENGTH]] ^
25190 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
251a0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a T_LENGTH</dt>.**
251b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
251c0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 size of any str
251d0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 ing or BLOB or t
251e0 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 able row, in byt
251f0 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 es.<dd>)^.**.**
25200 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 [[SQLITE_LIMIT_S
25210 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 QL_LENGTH]] ^(<d
25220 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 t>SQLITE_LIMIT_S
25230 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a QL_LENGTH</dt>.*
25240 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
25250 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 m length of an S
25260 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e QL statement, in
25270 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a bytes.</dd>)^.*
25280 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
25290 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c MIT_COLUMN]] ^(<
252a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
252b0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c COLUMN</dt>.** <
252c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
252d0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
252e0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 in a table defi
252f0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 nition or in the
25300 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f .** result set o
25310 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 f a [SELECT] or
25320 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
25330 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
25340 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 an index.** or
25350 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f in an ORDER BY o
25360 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 r GROUP BY claus
25370 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 e.</dd>)^.**.**
25380 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 [[SQLITE_LIMIT_E
25390 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 XPR_DEPTH]] ^(<d
253a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 t>SQLITE_LIMIT_E
253b0 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a XPR_DEPTH</dt>.*
253c0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
253d0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 m depth of the p
253e0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 arse tree on any
253f0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 expression.</dd
25400 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
25410 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
25420 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 D_SELECT]] ^(<dt
25430 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f >SQLITE_LIMIT_CO
25440 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 MPOUND_SELECT</d
25450 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
25460 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
25470 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f terms in a compo
25480 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 und SELECT state
25490 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ment.</dd>)^.**.
254a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
254b0 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 T_VDBE_OP]] ^(<d
254c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
254d0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c DBE_OP</dt>.** <
254e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
254f0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 umber of instruc
25500 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 tions in a virtu
25510 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 al machine progr
25520 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d am.** used to im
25530 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 plement an SQL s
25540 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 tatement. This
25550 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 limit is not cur
25560 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 rently.** enforc
25570 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 ed, though that
25580 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 might be added i
25590 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
255a0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
255b0 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a te.</dd>)^.**.**
255c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
255d0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e FUNCTION_ARG]] ^
255e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
255f0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f T_FUNCTION_ARG</
25600 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
25610 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
25620 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 arguments on a
25630 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e function.</dd>)^
25640 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
25650 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d LIMIT_ATTACHED]]
25660 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
25670 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 MIT_ATTACHED</dt
25680 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
25690 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b imum number of [
256a0 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 ATTACH | attache
256b0 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c d databases].)^<
256c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
256d0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
256e0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a ATTERN_LENGTH]].
256f0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
25700 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
25710 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a RN_LENGTH</dt>.*
25720 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
25730 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 m length of the
25740 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 pattern argument
25750 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f to the [LIKE] o
25760 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 r.** [GLOB] oper
25770 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ators.</dd>)^.**
25780 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
25790 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
257a0 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ER]].** ^(<dt>SQ
257b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
257c0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a BLE_NUMBER</dt>.
257d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
257e0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 um index number
257f0 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 of any [paramete
25800 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 r] in an SQL sta
25810 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 tement.)^.**.**
25820 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 [[SQLITE_LIMIT_T
25830 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e RIGGER_DEPTH]] ^
25840 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
25850 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c T_TRIGGER_DEPTH<
25860 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
25870 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
25880 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 recursion for t
25890 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a riggers.</dd>)^.
258a0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
258b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
258c0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
258d0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 0.#de
258e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
258f0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 T_SQL_LENGTH
25900 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 1.#d
25910 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
25920 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 IT_COLUMN
25930 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
25940 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
25950 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 MIT_EXPR_DEPTH
25960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 3.
25970 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
25980 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
25990 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 LECT 4
259a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
259b0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 LIMIT_VDBE_OP
259c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
259d0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
259e0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
259f0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 ARG
25a00 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
25a10 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
25a20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
25a30 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
25a40 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
25a50 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 TTERN_LENGTH
25a60 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
25a70 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
25a80 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 LE_NUMBER
25a90 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
25aa0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
25ab0 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 ER_DEPTH
25ac0 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 10../*.** CA
25ad0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e PI3REF: Compilin
25ae0 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 g An SQL Stateme
25af0 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 nt.** KEYWORDS:
25b00 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 {SQL statement c
25b10 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 ompiler}.**.** T
25b20 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c o execute an SQL
25b30 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 query, it must
25b40 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 first be compile
25b50 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f d into a byte-co
25b60 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 de.** program us
25b70 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 ing one of these
25b80 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
25b90 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
25ba0 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 ent, "db", is a
25bb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
25bc0 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 tion] obtained f
25bd0 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 rom a.** prior s
25be0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
25bf0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
25c00 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
25c10 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 n_v2()] or.** [s
25c20 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
25c30 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 . The database
25c40 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 connection must
25c50 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c not have been cl
25c60 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 osed..**.** The
25c70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c second argument,
25c80 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 "zSql", is the
25c90 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
25ca0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 compiled, encode
25cb0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 d.** as either U
25cc0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 TF-8 or UTF-16.
25cd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
25ce0 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 pare() and sqlit
25cf0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a e3_prepare_v2().
25d00 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 ** interfaces us
25d10 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c e UTF-8, and sql
25d20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
25d30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
25d40 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 pare16_v2().** u
25d50 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a se UTF-16..**.**
25d60 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 ^If the nByte a
25d70 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 rgument is less
25d80 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 than zero, then
25d90 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 zSql is read up
25da0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 to the.** first
25db0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
25dc0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f ^If nByte is no
25dd0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
25de0 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d it is the maxim
25df0 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 um.** number of
25e00 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d bytes read from
25e10 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 zSql. ^When nB
25e20 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 yte is non-negat
25e30 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c ive, the.** zSql
25e40 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 string ends at
25e50 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 either the first
25e60 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 '\000' or '\u00
25e70 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 00' character or
25e80 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 .** the nByte-th
25e90 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 byte, whichever
25ea0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 comes first. If
25eb0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 the caller know
25ec0 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 s.** that the su
25ed0 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 pplied string is
25ee0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c nul-terminated,
25ef0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 then there is a
25f00 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 small.** perfor
25f10 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 mance advantage
25f20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 to be gained by
25f30 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 passing an nByte
25f40 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a parameter that.
25f50 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 ** is equal to t
25f60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
25f70 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 es in the input
25f80 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 string <i>includ
25f90 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e ing</i>.** the n
25fa0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 ul-terminator by
25fb0 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65 tes as this save
25fc0 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 s SQLite from ha
25fd0 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 ving to.** make
25fe0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e a copy of the in
25ff0 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a put string..**.*
26000 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 * ^If pzTail is
26010 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 not NULL then *p
26020 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f zTail is made to
26030 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 point to the fi
26040 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 rst byte.** past
26050 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
26060 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d first SQL statem
26070 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 ent in zSql. Th
26080 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c ese routines onl
26090 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 y.** compile the
260a0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 first statement
260b0 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a in zSql, so *pz
260c0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 Tail is left poi
260d0 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 nting to.** what
260e0 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 remains uncompi
260f0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 led..**.** ^*ppS
26100 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e tmt is left poin
26110 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c ting to a compil
26120 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ed [prepared sta
26130 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e tement] that can
26140 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 be.** executed
26150 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 using [sqlite3_s
26160 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 tep()]. ^If the
26170 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 re is an error,
26180 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a *ppStmt is set.*
26190 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 * to NULL. ^If
261a0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 the input text c
261b0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 ontains no SQL (
261c0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 if the input is
261d0 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 an empty.** stri
261e0 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 ng or a comment)
261f0 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 then *ppStmt is
26200 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a set to NULL..**
26210 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f The calling pro
26220 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e cedure is respon
26230 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 sible for deleti
26240 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a ng the compiled.
26250 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
26260 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
26270 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 finalize()] afte
26280 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 r it has finishe
26290 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 d with it..** pp
262a0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 Stmt may not be
262b0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 NULL..**.** ^On
262c0 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c success, the sql
262d0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 ite3_prepare() f
262e0 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 amily of routine
262f0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 s return [SQLITE
26300 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 _OK];.** otherwi
26310 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 se an [error cod
26320 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
26330 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
26340 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 3_prepare_v2() a
26350 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
26360 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 re16_v2() interf
26370 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f aces are.** reco
26380 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 mmended for all
26390 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 new programs. Th
263a0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 e two older inte
263b0 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 rfaces are retai
263c0 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 ned.** for backw
263d0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
263e0 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 ty, but their us
263f0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 e is discouraged
26400 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 ..** ^In the "v2
26410 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 " interfaces, th
26420 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
26430 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 ment.** that is
26440 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 returned (the [s
26450 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
26460 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 ect) contains a
26470 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
26480 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 riginal SQL text
26490 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 . This causes th
264a0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
264b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a )] interface to.
264c0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 ** behave differ
264d0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 ently in three w
264e0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a ays:.**.** <ol>.
264f0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
26500 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
26510 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
26520 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
26530 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
26540 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
26550 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
26560 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
26570 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
26580 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
26590 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
265a0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
265b0 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 t again. As many
265c0 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f as [SQLITE_MAX_
265d0 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a SCHEMA_RETRY].**
265e0 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 retries will oc
265f0 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 cur before sqlit
26600 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 e3_step() gives
26610 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 up and returns a
26620 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 n error..** </li
26630 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
26640 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f ^When an error o
26650 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
26660 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
26670 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
26680 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
26690 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
266a0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
266b0 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 s]. ^The legacy
266c0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 behavior was th
266d0 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 at.** [sqlite3_s
266e0 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c tep()] would onl
266f0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 y return a gener
26700 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ic [SQLITE_ERROR
26710 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a ] result code.**
26720 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
26730 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 tion would have
26740 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
26750 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
26760 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 3_reset()].** in
26770 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 order to find t
26780 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
26790 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
267a0 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
267b0 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
267c0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
267d0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
267e0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
267f0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
26800 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
26810 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 *.** <li>.** ^If
26820 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 the specific va
26830 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 lue bound to [pa
26840 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 rameter | host p
26850 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
26860 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 .** WHERE claus
26870 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 e might influenc
26880 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 e the choice of
26890 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 query plan for a
268a0 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 statement,.** t
268b0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
268c0 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 t will be automa
268d0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c tically recompil
268e0 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 ed, as if there
268f0 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 had been .** a s
26900 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e chema change, on
26910 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c the first [sql
26920 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
26930 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 l following any
26940 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 change.** to the
26950 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
26960 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 ext | bindings]
26970 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 of that [paramet
26980 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 er]. .** ^The sp
26990 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 ecific value of
269a0 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 WHERE-clause [pa
269b0 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 rameter] might i
269c0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a nfluence the .**
269d0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
269e0 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 plan if the par
269f0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 ameter is the le
26a00 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ft-hand side of
26a10 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b a [LIKE].** or [
26a20 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f GLOB] operator o
26a30 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 r if the paramet
26a40 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 er is compared t
26a50 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c o an indexed col
26a60 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b umn.** and the [
26a70 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 SQLITE_ENABLE_ST
26a80 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d AT3] compile-tim
26a90 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
26aa0 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a led..** </li>.**
26ab0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 </ol>.*/.int sq
26ac0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 lite3_prepare(.
26ad0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
26ae0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
26af0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
26b00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
26b10 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
26b20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
26b30 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
26b40 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
26b50 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
26b60 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
26b70 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
26b80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
26b90 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
26ba0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
26bb0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
26bc0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
26bd0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
26be0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
26bf0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
26c00 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
26c10 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
26c20 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
26c30 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
26c40 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
26c50 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
26c60 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
26c70 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
26c80 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
26c90 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
26ca0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
26cb0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
26cc0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
26cd0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
26ce0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
26cf0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
26d00 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
26d10 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
26d20 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
26d30 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
26d40 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
26d50 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 repare16(. sqli
26d60 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
26d70 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
26d80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
26d90 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
26da0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
26db0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
26dc0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
26dd0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
26de0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
26df0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
26e00 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
26e10 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
26e20 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
26e30 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
26e40 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
26e50 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
26e60 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
26e70 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
26e80 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
26e90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
26ea0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
26eb0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
26ec0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
26ed0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
26ee0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
26ef0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
26f00 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
26f10 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
26f20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
26f30 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
26f40 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
26f50 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
26f60 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
26f70 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
26f80 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
26f90 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
26fa0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
26fb0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
26fc0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
26fd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
26fe0 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 F: Retrieving St
26ff0 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a atement SQL.**.*
27000 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 * ^This interfac
27010 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
27020 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 retrieve a save
27030 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 d copy of the or
27040 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 iginal.** SQL te
27050 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 xt used to creat
27060 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 e a [prepared st
27070 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 atement] if that
27080 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a statement was.*
27090 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 * compiled using
270a0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
270b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
270c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
270d0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 re16_v2()]..*/.c
270e0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
270f0 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 e3_sql(sqlite3_s
27100 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
27110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
27120 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 termine If An SQ
27130 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 L Statement Writ
27140 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a es The Database.
27150 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
27160 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
27170 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (X) interface re
27180 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
27190 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 zero) if.** and
271a0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 only if the [pre
271b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
271c0 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 X makes no dire
271d0 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a ct changes to.**
271e0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
271f0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
27200 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 e..**.** Note th
27210 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d at [application-
27220 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
27230 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 tions] or.** [vi
27240 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 rtual tables] mi
27250 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 ght change the d
27260 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 atabase indirect
27270 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 ly as a side eff
27280 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 ect. .** ^(For
27290 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 example, if an a
272a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
272b0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 es a function "e
272c0 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 val()" that .**
272d0 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 calls [sqlite3_e
272e0 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 xec()], then the
272f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 following SQL s
27300 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a tatement would.*
27310 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 * change the dat
27320 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 abase file throu
27330 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a gh side-effects:
27340 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
27350 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 te><pre>.** S
27360 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 ELECT eval('DELE
27370 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f TE FROM t1') FRO
27380 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c M t2;.** </pre><
27390 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
273a0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 ** But because t
273b0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
273c0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
273d0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
273e0 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 se file.** direc
273f0 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d tly, sqlite3_stm
27400 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 t_readonly() wou
27410 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 ld still return
27420 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 true.)^.**.** ^T
27430 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 ransaction contr
27440 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 ol statements su
27450 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b ch as [BEGIN], [
27460 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 COMMIT], [ROLLBA
27470 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 CK],.** [SAVEPOI
27480 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 NT], and [RELEAS
27490 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 E] cause sqlite3
274a0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
274b0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c to return true,
274c0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 .** since the st
274d0 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c atements themsel
274e0 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 ves do not actua
274f0 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 lly modify the d
27500 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 atabase but.** r
27510 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 ather they contr
27520 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 ol the timing of
27530 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 when other stat
27540 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 ements modify th
27550 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 e .** database.
27560 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 ^The [ATTACH] a
27570 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 nd [DETACH] stat
27580 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 ements also caus
27590 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d e.** sqlite3_stm
275a0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
275b0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 return true sinc
275c0 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 e, while those s
275d0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 tatements.** cha
275e0 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 nge the configur
275f0 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 ation of a datab
27600 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 ase connection,
27610 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 they do not make
27620 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 .** changes to
27630 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
27640 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
27650 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e s on disk..*/.in
27660 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 t sqlite3_stmt_r
27670 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f eadonly(sqlite3_
27680 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
27690 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
276a0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 etermine If A Pr
276b0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
276c0 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a Has Been Reset.
276d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
276e0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 e3_stmt_busy(S)
276f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
27700 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f s true (non-zero
27710 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 ) if the.** [pre
27720 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
27730 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 S has been step
27740 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 ped at least onc
27750 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c e using .** [sql
27760 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 ite3_step(S)] bu
27770 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f t has not run to
27780 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f completion and/
27790 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 or has not .** b
277a0 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 een reset using
277b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
277c0 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 )]. ^The sqlite
277d0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 3_stmt_busy(S).*
277e0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 * interface retu
277f0 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 rns false if S i
27800 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
27810 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 . If S is not a
27820 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 .** NULL pointe
27830 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 r and is not a p
27840 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 ointer to a vali
27850 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
27860 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 ement].** object
27870 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
27880 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
27890 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e and probably un
278a0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a desirable..**.**
278b0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
278c0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 can be used in c
278d0 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 ombination [sqli
278e0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d te3_next_stmt()]
278f0 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c .** to locate al
27900 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 l prepared state
27910 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 ments associated
27920 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 with a database
27930 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 .** connection
27940 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 that are in need
27950 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e of being reset.
27960 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 This can be us
27970 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 ed,.** for examp
27980 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 le, in diagnosti
27990 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 c routines to se
279a0 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 arch for prepare
279b0 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 d .** statements
279c0 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e that are holdin
279d0 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 g a transaction
279e0 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c open..*/.int sql
279f0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 ite3_stmt_busy(s
27a00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
27a10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27a20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 Dynamically Type
27a30 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a d Value Object.*
27a40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f * KEYWORDS: {pro
27a50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
27a60 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 alue} {unprotect
27a70 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
27a80 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 }.**.** SQLite u
27a90 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f ses the sqlite3_
27aa0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 value object to
27ab0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 represent all va
27ac0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e lues.** that can
27ad0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 be stored in a
27ae0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 database table.
27af0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
27b00 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f mic typing.** fo
27b10 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 r the values it
27b20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 stores. ^Values
27b30 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 stored in sqlit
27b40 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
27b50 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 .** can be integ
27b60 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
27b70 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
27b80 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
27b90 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 ULL..**.** An sq
27ba0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
27bb0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 ct may be either
27bc0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 "protected" or
27bd0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a "unprotected"..*
27be0 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 * Some interface
27bf0 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 s require a prot
27c00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
27c10 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 lue. Other inte
27c20 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 rfaces.** will a
27c30 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 ccept either a p
27c40 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 rotected or an u
27c50 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
27c60 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 e3_value..** Eve
27c70 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ry interface tha
27c80 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 t accepts sqlite
27c90 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 3_value argument
27ca0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 s specifies.** w
27cb0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 hether or not it
27cc0 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 requires a prot
27cd0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
27ce0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 lue..**.** The t
27cf0 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 erms "protected"
27d00 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 and "unprotecte
27d10 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 d" refer to whet
27d20 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 her or not.** a
27d30 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 mutex is held.
27d40 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 An internal mute
27d50 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 x is held for a
27d60 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
27d70 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
27d80 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 t but no mutex i
27d90 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e s held for an un
27da0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
27db0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
27dc0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 t. If SQLite is
27dd0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 compiled to be
27de0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a single-threaded.
27df0 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 ** (with [SQLITE
27e00 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 _THREADSAFE=0] a
27e10 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 nd with [sqlite3
27e20 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 _threadsafe()] r
27e30 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f eturning 0).** o
27e40 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 r if SQLite is r
27e50 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 un in one of red
27e60 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 uced mutex modes
27e70 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [SQLITE_CON
27e80 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
27e90 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
27ea0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d FIG_MULTITHREAD]
27eb0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 .** then there i
27ec0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e s no distinction
27ed0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 between protect
27ee0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 ed and unprotect
27ef0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
27f00 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 lue objects and
27f10 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 they can be used
27f20 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 interchangeably
27f30 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 . However,.** f
27f40 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 or maximum code
27f50 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 portability it i
27f60 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
27f70 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a at applications.
27f80 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 ** still make th
27f90 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 e distinction be
27fa0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
27fb0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
27fc0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
27fd0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 objects even wh
27fe0 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 en not strictly
27ff0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
28000 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
28010 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 ue objects that
28020 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 are passed as pa
28030 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 rameters into th
28040 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
28050 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 ion of [applicat
28060 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
28070 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 functions] are p
28080 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 rotected..** ^Th
28090 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
280a0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
280b0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
280c0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
280d0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a s unprotected..*
280e0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 * Unprotected sq
280f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
28100 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 cts may only be
28110 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 used with.** [sq
28120 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
28130 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ue()] and [sqlit
28140 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d e3_bind_value()]
28150 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
28160 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 3_value_blob | s
28170 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
28180 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a e()] family of.*
28190 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 * interfaces req
281a0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 uire protected s
281b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
281c0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ects..*/.typedef
281d0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 struct Mem sqli
281e0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a te3_value;../*.*
281f0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
28200 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 Function Context
28210 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 Object.**.** Th
28220 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 e context in whi
28230 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 ch an SQL functi
28240 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 on executes is s
28250 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 tored in an.** s
28260 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
28270 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 bject. ^A point
28280 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 er to an sqlite3
28290 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a _context object.
282a0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 ** is always fir
282b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
282c0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
282d0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
282e0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c ns]..** The appl
282f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
28300 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 SQL function imp
28310 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c lementation will
28320 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f pass this.** po
28330 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e inter through in
28340 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c to calls to [sql
28350 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 ite3_result_int
28360 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 | sqlite3_result
28370 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
28380 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
28390 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f xt()], [sqlite3_
283a0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a user_data()],.**
283b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
283c0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 t_db_handle()],
283d0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 [sqlite3_get_aux
283e0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f data()],.** and/
283f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f or [sqlite3_set_
28400 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 auxdata()]..*/.t
28410 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
28420 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 lite3_context sq
28430 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a lite3_context;..
28440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
28450 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 Binding Values T
28460 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 o Prepared State
28470 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ments.** KEYWORD
28480 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 S: {host paramet
28490 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 er} {host parame
284a0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 ters} {host para
284b0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b meter name}.** K
284c0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 EYWORDS: {SQL pa
284d0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 rameter} {SQL pa
284e0 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d rameters} {param
284f0 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a eter binding}.**
28500 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c .** ^(In the SQL
28510 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
28520 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
28530 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
28540 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 and its variants
28550 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 ,.** literals ma
28560 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 y be replaced by
28570 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 a [parameter] t
28580 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 hat matches one
28590 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 of following.**
285a0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a templates:.**.**
285b0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
285c0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
285d0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 * <li> :VVV.**
285e0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c <li> @VVV.** <l
285f0 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
28600 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 >.**.** In the t
28610 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 emplates above,
28620 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 NNN represents a
28630 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 n integer litera
28640 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 l,.** and VVV re
28650 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 presents an alph
28660 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 anumeric identif
28670 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c ier.)^ ^The val
28680 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ues of these.**
28690 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f parameters (also
286a0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 called "host pa
286b0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f rameter names" o
286c0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 r "SQL parameter
286d0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 s").** can be se
286e0 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 t using the sqli
286f0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
28700 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 tines defined he
28710 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 re..**.** ^The f
28720 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
28730 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
28740 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 d_*() routines i
28750 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f s always.** a po
28760 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
28770 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
28780 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d ct returned from
28790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
287a0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 pare_v2()] or it
287b0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a s variants..**.*
287c0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 * ^The second ar
287d0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
287e0 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 dex of the SQL p
287f0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 arameter to be s
28800 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 et..** ^The left
28810 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 most SQL paramet
28820 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
28830 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 of 1. ^When the
28840 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 same named.** S
28850 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 QL parameter is
28860 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f used more than o
28870 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 nce, second and
28880 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 subsequent.** oc
28890 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 currences have t
288a0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 he same index as
288b0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 the first occur
288c0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 rence..** ^The i
288d0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 ndex for named p
288e0 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 arameters can be
288f0 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 looked up using
28900 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
28910 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
28920 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 index()] API if
28930 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 desired. ^The i
28940 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e ndex.** for "?NN
28950 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 N" parameters is
28960 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e the value of NN
28970 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 N..** ^The NNN v
28980 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 alue must be bet
28990 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b ween 1 and the [
289a0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
289b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 .** parameter [S
289c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
289d0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 ABLE_NUMBER] (de
289e0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 fault value: 999
289f0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 )..**.** ^The th
28a00 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
28a10 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e the value to bin
28a20 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 d to the paramet
28a30 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 er..** ^If the t
28a40 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
28a50 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
28a60 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
28a70 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a _bind_text16().*
28a80 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e * or sqlite3_bin
28a90 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 d_blob() is a NU
28aa0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
28ab0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
28ac0 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 eter.** is ignor
28ad0 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 ed and the end r
28ae0 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d esult is the sam
28af0 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e e as sqlite3_bin
28b00 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 d_null()..**.**
28b10 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 ^(In those routi
28b20 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 nes that have a
28b30 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
28b40 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 its value is th
28b50 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 e.** number of b
28b60 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 ytes in the para
28b70 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c meter. To be cl
28b80 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 ear: the value i
28b90 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
28ba0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 of <u>bytes</u>
28bb0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f in the value, no
28bc0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
28bd0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a characters.)^.**
28be0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 ^If the fourth
28bf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
28c00 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
28c10 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
28c20 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 _text16().** is
28c30 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
28c40 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
28c50 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 string is.** th
28c60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
28c70 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 s up to the firs
28c80 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
28c90 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 r..** If the fou
28ca0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
28cb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
28cc0 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 ob() is negative
28cd0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 , then.** the be
28ce0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
28cf0 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e ned..** If a non
28d00 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 -negative fourth
28d10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 parameter is pr
28d20 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 ovided to sqlite
28d30 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 3_bind_text().**
28d40 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
28d50 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 _text16() then t
28d60 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 hat parameter mu
28d70 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
28d80 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 ffset.** where t
28d90 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f he NUL terminato
28da0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 r would occur as
28db0 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e suming the strin
28dc0 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 g were NUL.** te
28dd0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e rminated. If an
28de0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 y NUL characters
28df0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f occur at byte o
28e00 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e ffsets less than
28e10 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f .** the value o
28e20 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
28e30 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 ameter then the
28e40 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
28e50 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 value will.** c
28e60 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 ontain embedded
28e70 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c NULs. The resul
28e80 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
28e90 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e involving strin
28ea0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 gs.** with embed
28eb0 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
28ec0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
28ed0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
28ee0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
28ef0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
28f00 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e _bind_text(), an
28f10 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e d.** sqlite3_bin
28f20 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 d_text16() is a
28f30 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 destructor used
28f40 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
28f50 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 e BLOB or.** str
28f60 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 ing after SQLite
28f70 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
28f80 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 th it. ^The des
28f90 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 tructor is calle
28fa0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 d.** to dispose
28fb0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 of the BLOB or s
28fc0 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 tring even if th
28fd0 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 e call to sqlite
28fe0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 3_bind_blob(),.*
28ff0 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 * sqlite3_bind_t
29000 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 ext(), or sqlite
29010 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 3_bind_text16()
29020 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 fails. .** ^If
29030 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
29040 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 nt is.** the spe
29050 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 cial value [SQLI
29060 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e TE_STATIC], then
29070 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
29080 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f that the.** info
29090 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 rmation is in st
290a0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 atic, unmanaged
290b0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
290c0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 ot need to be fr
290d0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 eed..** ^If the
290e0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
290f0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
29100 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
29110 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
29120 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
29130 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
29140 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
29150 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
29160 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
29170 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
29180 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
29190 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
291a0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 blob() routine b
291b0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c inds a BLOB of l
291c0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 ength N that.**
291d0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a is filled with z
291e0 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 eroes. ^A zerob
291f0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 lob uses a fixed
29200 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 amount of memor
29210 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e y.** (just an in
29220 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 teger to hold it
29230 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 s size) while it
29240 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 is being proces
29250 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 sed..** Zeroblob
29260 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 s are intended t
29270 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 o serve as place
29280 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 holders for BLOB
29290 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 s whose.** conte
292a0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 nt is later writ
292b0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ten using.** [sq
292c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 lite3_blob_open
292d0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c | incremental BL
292e0 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 OB I/O] routines
292f0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 ..** ^A negative
29300 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a value for the z
29310 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 eroblob results
29320 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 in a zero-length
29330 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 BLOB..**.** ^If
29340 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 any of the sqli
29350 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
29360 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
29370 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
29380 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 nter.** for the
29390 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
293a0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 ent] or with a p
293b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
293c0 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b t for which.** [
293d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
293e0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 has been called
293f0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 more recently th
29400 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 an [sqlite3_rese
29410 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 t()],.** then th
29420 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 e call will retu
29430 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 rn [SQLITE_MISUS
29440 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 E]. If any sqli
29450 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 te3_bind_().** r
29460 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 outine is passed
29470 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
29480 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 tement] that has
29490 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c been finalized,
294a0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 the.** result i
294b0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
294c0 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c probably harmful
294d0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 ..**.** ^Binding
294e0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 s are not cleare
294f0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
29500 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 3_reset()] routi
29510 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 ne..** ^Unbound
29520 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 parameters are i
29530 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 nterpreted as NU
29540 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 LL..**.** ^The s
29550 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f qlite3_bind_* ro
29560 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
29570 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
29580 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 cess or an.** [e
29590 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e rror code] if an
295a0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ything goes wron
295b0 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 g..** ^[SQLITE_R
295c0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 ANGE] is returne
295d0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 d if the paramet
295e0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f er.** index is o
295f0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b ut of range. ^[
29600 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 SQLITE_NOMEM] is
29610 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c returned if mal
29620 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a loc() fails..**.
29630 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
29640 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
29650 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a eter_count()],.*
29660 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
29670 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
29680 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
29690 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
296a0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 ndex()]..*/.int
296b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
296c0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
296d0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
296e0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
296f0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
29700 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 qlite3_bind_doub
29710 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
29720 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a , int, double);.
29730 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
29740 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d _int(sqlite3_stm
29750 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 t*, int, int);.i
29760 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
29770 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
29780 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 mt*, int, sqlite
29790 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 3_int64);.int sq
297a0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 lite3_bind_null(
297b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
297c0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 nt);.int sqlite3
297d0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 _bind_text(sqlit
297e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
297f0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 onst char*, int
29800 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a n, void(*)(void*
29810 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
29820 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 bind_text16(sqli
29830 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
29840 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
29850 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
29860 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
29870 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 ind_value(sqlite
29880 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
29890 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 nst sqlite3_valu
298a0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
298b0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 _bind_zeroblob(s
298c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
298d0 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a t, int n);../*.*
298e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
298f0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 er Of SQL Parame
29900 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ters.**.** ^This
29910 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
29920 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 used to find the
29930 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 number of [SQL
29940 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 parameters].** i
29950 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
29960 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 atement]. SQL p
29970 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f arameters are to
29980 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 kens of the.** f
29990 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c orm "?", "?NNN",
299a0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c ":AAA", "$AAA",
299b0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 or "@AAA" that
299c0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 serve as.** plac
299d0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c eholders for val
299e0 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 ues that are [sq
299f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
29a00 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 | bound].** to t
29a10 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 he parameters at
29a20 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a a later time..*
29a30 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 *.** ^(This rout
29a40 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 ine actually ret
29a50 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f urns the index o
29a60 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 f the largest (r
29a70 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 ightmost).** par
29a80 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 ameter. For all
29a90 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e forms except ?NN
29aa0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 N, this will cor
29ab0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a respond to the.*
29ac0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 * number of uniq
29ad0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ue parameters.
29ae0 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 If parameters of
29af0 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 the ?NNN form a
29b00 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 re used,.** ther
29b10 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e e may be gaps in
29b20 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a the list.)^.**.
29b30 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
29b40 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
29b50 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
29b60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
29b70 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
29b80 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
29b90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
29ba0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
29bb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
29bc0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
29bd0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 t(sqlite3_stmt*)
29be0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
29bf0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 F: Name Of A Hos
29c00 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a t Parameter.**.*
29c10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
29c20 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
29c30 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 me(P,N) interfac
29c40 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 e returns.** the
29c50 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 name of the N-t
29c60 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 h [SQL parameter
29c70 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 ] in the [prepar
29c80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
29c90 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 .** ^(SQL parame
29ca0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
29cb0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
29cc0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
29cd0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 $AAA".** have a
29ce0 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 name which is th
29cf0 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 e string "?NNN"
29d00 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
29d10 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
29d20 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
29d30 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
29d40 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a , the initial ":
29d50 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 " or "$" or "@"
29d60 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 or "?".** is inc
29d70 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 luded as part of
29d80 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 the name.)^.**
29d90 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 ^Parameters of t
29da0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 he form "?" with
29db0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 out a following
29dc0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 integer have no
29dd0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 name.** and are
29de0 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 referred to as "
29df0 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e nameless" or "an
29e00 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 onymous paramete
29e10 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rs"..**.** ^The
29e20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d first host param
29e30 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
29e40 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
29e50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c *.** ^If the val
29e60 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 ue N is out of r
29e70 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e ange or if the N
29e80 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 -th parameter is
29e90 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 .** nameless, th
29ea0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 en NULL is retur
29eb0 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 ned. ^The retur
29ec0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a ned string is.**
29ed0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 always in UTF-8
29ee0 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 encoding even i
29ef0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 f the named para
29f00 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 meter was.** ori
29f10 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 ginally specifie
29f20 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b d as UTF-16 in [
29f30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
29f40 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 6()] or.** [sqli
29f50 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
29f60 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
29f70 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
29f80 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
29f90 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
29fa0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
29fb0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
29fc0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
29fd0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
29fe0 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 ex()]..*/.const
29ff0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 char *sqlite3_bi
2a000 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
2a010 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2a020 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 int);../*.** CA
2a030 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 PI3REF: Index Of
2a040 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 A Parameter Wit
2a050 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a h A Given Name.*
2a060 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
2a070 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c index of an SQL
2a080 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e parameter given
2a090 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 its name. ^The
2a0a0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 .** index value
2a0b0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 returned is suit
2a0c0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 able for use as
2a0d0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 the second.** pa
2a0e0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2a0f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
2a100 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 lite3_bind()].
2a110 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 ^A zero.** is re
2a120 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 turned if no mat
2a130 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 ching parameter
2a140 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 is found. ^The
2a150 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d parameter.** nam
2a160 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 e must be given
2a170 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 in UTF-8 even if
2a180 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
2a190 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 atement.** was p
2a1a0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 repared from UTF
2a1b0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b -16 text using [
2a1c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2a1d0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
2a1e0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
2a1f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
2a200 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
2a210 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2a220 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
2a230 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
2a240 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2a250 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e _index()]..*/.in
2a260 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 t sqlite3_bind_p
2a270 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 arameter_index(s
2a280 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f qlite3_stmt*, co
2a290 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
2a2a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2a2b0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e F: Reset All Bin
2a2c0 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 dings On A Prepa
2a2d0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a red Statement.**
2a2e0 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f .** ^Contrary to
2a2f0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f the intuition o
2a300 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 f many, [sqlite3
2a310 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e _reset()] does n
2a320 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 ot reset.** the
2a330 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2a340 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f ob | bindings] o
2a350 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
2a360 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 atement]..** ^Us
2a370 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
2a380 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 o reset all host
2a390 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e parameters to N
2a3a0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ULL..*/.int sqli
2a3b0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
2a3c0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
2a3d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2a3e0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f EF: Number Of Co
2a3f0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c lumns In A Resul
2a400 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 t Set.**.** ^Ret
2a410 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f urn the number o
2a420 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
2a430 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 result set retu
2a440 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b rned by the.** [
2a450 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2a460 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 nt]. ^This routi
2a470 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 ne returns 0 if
2a480 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a pStmt is an SQL.
2a490 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 ** statement tha
2a4a0 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 t does not retur
2a4b0 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d n data (for exam
2a4c0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 ple an [UPDATE])
2a4d0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2a4e0 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f : [sqlite3_data_
2a4f0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 count()].*/.int
2a500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
2a510 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
2a520 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2a530 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 * CAPI3REF: Colu
2a540 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 mn Names In A Re
2a550 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e sult Set.**.** ^
2a560 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
2a570 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 eturn the name a
2a580 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 ssigned to a par
2a590 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a ticular column.*
2a5a0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 * in the result
2a5b0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
2a5c0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 ] statement. ^T
2a5d0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
2a5e0 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 n_name().** inte
2a5f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2a600 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
2a610 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
2a620 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 -8 string.** and
2a630 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2a640 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 name16() returns
2a650 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
2a660 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
2a670 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
2a680 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 . ^The first pa
2a690 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
2a6a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2a6b0 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c nt].** that impl
2a6c0 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 ements the [SELE
2a6d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e CT] statement. ^
2a6e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
2a6f0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 eter is the.** c
2a700 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e olumn number. ^
2a710 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
2a720 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e umn is number 0.
2a730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 .**.** ^The retu
2a740 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e rned string poin
2a750 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ter is valid unt
2a760 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 il either the [p
2a770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2a780 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 t].** is destroy
2a790 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
2a7a0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
2a7b0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e til the statemen
2a7c0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c t is automatical
2a7d0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 ly.** reprepared
2a7e0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 by the first ca
2a7f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
2a800 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 tep()] for a par
2a810 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f ticular run.** o
2a820 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 r until the next
2a830 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
2a840 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
2a850 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
2a860 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 umn_name16() on
2a870 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e the same column.
2a880 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 .**.** ^If sqlit
2a890 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c e3_malloc() fail
2a8a0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f s during the pro
2a8b0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 cessing of eithe
2a8c0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f r routine.** (fo
2a8d0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 r example during
2a8e0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 a conversion fr
2a8f0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d om UTF-8 to UTF-
2a900 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 16) then a.** NU
2a910 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
2a920 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
2a930 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 he name of a res
2a940 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 ult column is th
2a950 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 e value of the "
2a960 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a AS" clause for.*
2a970 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 * that column, i
2a980 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 f there is an AS
2a990 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 clause. If the
2a9a0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 re is no AS clau
2a9b0 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e se.** then the n
2a9c0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d ame of the colum
2a9d0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 n is unspecified
2a9e0 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 and may change
2a9f0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 from.** one rele
2aa00 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f ase of SQLite to
2aa10 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f the next..*/.co
2aa20 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
2aa30 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 3_column_name(sq
2aa40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2aa50 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 N);.const void
2aa60 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2aa70 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
2aa80 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f tmt*, int N);../
2aa90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
2aaa0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e ource Of Data In
2aab0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
2aac0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
2aad0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 tines provide a
2aae0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 means to determi
2aaf0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c ne the database,
2ab00 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 table, and.** t
2ab10 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
2ab20 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f is the origin o
2ab30 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 f a particular r
2ab40 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a esult column in.
2ab50 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 ** [SELECT] stat
2ab60 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e ement..** ^The n
2ab70 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
2ab80 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 ase or table or
2ab90 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 column can be re
2aba0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 turned as.** eit
2abb0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 her a UTF-8 or U
2abc0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e TF-16 string. ^
2abd0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 The _database_ r
2abe0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a outines return.*
2abf0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e * the database n
2ac00 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f ame, the _table_
2ac10 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2ac20 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c the table name,
2ac30 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 and.** the orig
2ac40 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 in_ routines ret
2ac50 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e urn the column n
2ac60 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ame..** ^The ret
2ac70 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
2ac80 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 valid until the
2ac90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2aca0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 ent] is destroye
2acb0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 d.** using [sqli
2acc0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2acd0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 or until the sta
2ace0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 tement is automa
2acf0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 tically.** repre
2ad00 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 pared by the fir
2ad10 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 st call to [sqli
2ad20 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 te3_step()] for
2ad30 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e a particular run
2ad40 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
2ad50 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
2ad60 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
2ad70 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
2ad80 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
2ad90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 .**.** ^The name
2ada0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 s returned are t
2adb0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 he original un-a
2adc0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 liased names of
2add0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c the.** database,
2ade0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 table, and colu
2adf0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 mn..**.** ^The f
2ae00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
2ae10 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
2ae20 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 s is a [prepared
2ae30 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
2ae40 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
2ae50 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
2ae60 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
2ae70 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
2ae80 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
2ae90 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
2aea0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
2aeb0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
2aec0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c ument..** ^The l
2aed0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 eft-most column
2aee0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 is column 0 for
2aef0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
2af00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 **.** ^If the Nt
2af10 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
2af20 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 d by the stateme
2af30 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 nt is an express
2af40 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 ion or.** subque
2af50 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 ry and is not a
2af60 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 column value, th
2af70 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 en all of these
2af80 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
2af90 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 .** NULL. ^Thes
2afa0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 e routine might
2afb0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c also return NULL
2afc0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
2afd0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a ocation error.**
2afe0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 occurs. ^Other
2aff0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
2b000 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
2b010 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
2b020 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f ase, table,.** o
2b030 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 r column that qu
2b040 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
2b050 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
2b060 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 from..**.** ^As
2b070 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
2b080 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
2b090 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e e whose names en
2b0a0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 d with "16" retu
2b0b0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 rn.** UTF-16 enc
2b0c0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 oded strings and
2b0d0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 the other funct
2b0e0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d ions return UTF-
2b0f0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 8..**.** ^These
2b100 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 APIs are only av
2b110 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c ailable if the l
2b120 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 ibrary was compi
2b130 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
2b140 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 [SQLITE_ENABLE_C
2b150 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 OLUMN_METADATA]
2b160 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 C-preprocessor s
2b170 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ymbol..**.** If
2b180 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
2b190 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
2b1a0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f more of these ro
2b1b0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 utines against t
2b1c0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 he same.** prepa
2b1d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e red statement an
2b1e0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 d column at the
2b1f0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
2b200 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a he results are.*
2b210 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
2b220 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
2b230 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
2b240 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 ne or more.** [s
2b250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
2b260 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f tabase_name | co
2b270 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e lumn metadata in
2b280 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 terfaces].** for
2b290 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 the same [prepa
2b2a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
2b2b0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e nd result column
2b2c0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 .** at the same
2b2d0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
2b2e0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2b2f0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ned..*/.const ch
2b300 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2b310 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
2b320 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2b330 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
2b340 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2b350 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
2b360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2b370 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
2b380 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2b390 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 able_name(sqlite
2b3a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
2b3b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2b3c0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
2b3d0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
2b3e0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
2b3f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2b400 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
2b410 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2b420 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
2b430 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2b440 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 origin_name16(sq
2b450 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2b460 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2b470 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 F: Declared Data
2b480 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 type Of A Query
2b490 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 Result.**.** ^(T
2b4a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2b4b0 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 er is a [prepare
2b4c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2b4d0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 If this stateme
2b4e0 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d nt is a [SELECT]
2b4f0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
2b500 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
2b510 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 the.** returned
2b520 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 result set of t
2b530 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 hat [SELECT] is
2b540 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 a table column (
2b550 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 not an.** expres
2b560 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
2b570 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 ) then the decla
2b580 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 red type of the
2b590 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 table.** column
2b5a0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 is returned.)^
2b5b0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
2b5c0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
2b5d0 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 set is an.** ex
2b5e0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
2b5f0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c uery, then a NUL
2b600 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
2b610 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 urned..** ^The r
2b620 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
2b630 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 s always UTF-8 e
2b640 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ncoded..**.** ^(
2b650 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 For example, giv
2b660 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
2b670 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 schema:.**.** CR
2b680 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 EATE TABLE t1(c1
2b690 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a VARIANT);.**.**
2b6a0 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 and the followi
2b6b0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 ng statement to
2b6c0 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a be compiled:.**.
2b6d0 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 ** SELECT c1 + 1
2b6e0 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a , c1 FROM t1;.**
2b6f0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
2b700 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 would return th
2b710 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e e string "VARIAN
2b720 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e T" for the secon
2b730 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 d result.** colu
2b740 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 mn (i==1), and a
2b750 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
2b760 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 r the first resu
2b770 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 lt column (i==0)
2b780 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 .)^.**.** ^SQLit
2b790 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 e uses dynamic r
2b7a0 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 un-time typing.
2b7b0 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 ^So just becaus
2b7c0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 e a column.** is
2b7d0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e declared to con
2b7e0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 tain a particula
2b7f0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 r type does not
2b800 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a mean that the.**
2b810 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 data stored in
2b820 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f that column is o
2b830 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 f the declared t
2b840 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a ype. SQLite is.
2b850 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 ** strongly type
2b860 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e d, but the typin
2b870 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 g is dynamic not
2b880 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a static. ^Type.
2b890 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
2b8a0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
2b8b0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
2b8c0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
2b8d0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
2b8e0 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
2b8f0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
2b900 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
2b910 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 ltype(sqlite3_st
2b920 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
2b930 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2b940 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 lumn_decltype16(
2b950 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2b960 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2b970 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e REF: Evaluate An
2b980 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
2b990 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 *.** After a [pr
2b9a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2b9b0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 ] has been prepa
2b9c0 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 red using either
2b9d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2b9e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
2b9f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2ba00 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
2ba10 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
2ba20 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
2ba30 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
2ba40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2ba50 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e e16()], this fun
2ba60 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 ction.** must be
2ba70 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
2ba80 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 ore times to eva
2ba90 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d luate the statem
2baa0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ent..**.** The d
2bab0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 etails of the be
2bac0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 havior of the sq
2bad0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 lite3_step() int
2bae0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a erface depend.**
2baf0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 on whether the
2bb00 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 statement was pr
2bb10 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 epared using the
2bb20 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 newer "v2" inte
2bb30 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 rface.** [sqlite
2bb40 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2bb50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
2bb60 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
2bb70 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 the older legacy
2bb80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 .** interface [s
2bb90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
2bba0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
2bbb0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 repare16()]. Th
2bbc0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 e use of the.**
2bbd0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 new "v2" interfa
2bbe0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2bbf0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 d for new applic
2bc00 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c ations but the l
2bc10 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
2bc20 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 ce will continue
2bc30 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
2bc40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 ..**.** ^In the
2bc50 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
2bc60 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
2bc70 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 ue will be eithe
2bc80 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c r [SQLITE_BUSY],
2bc90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
2bca0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ], [SQLITE_ROW],
2bcb0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
2bcc0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 or [SQLITE_MISU
2bcd0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 SE]..** ^With th
2bce0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2bcf0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 , any of the oth
2bd00 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 er [result codes
2bd10 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
2bd20 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
2bd30 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 might be returne
2bd40 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a d as well..**.**
2bd50 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 ^[SQLITE_BUSY]
2bd60 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 means that the d
2bd70 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 atabase engine w
2bd80 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 as unable to acq
2bd90 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 uire the.** data
2bda0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 base locks it ne
2bdb0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f eds to do its jo
2bdc0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 b. ^If the stat
2bdd0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d ement is a [COMM
2bde0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 IT].** or occurs
2bdf0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
2be00 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
2be10 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
2be20 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
2be30 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
2be40 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
2be50 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e ot a [COMMIT] an
2be60 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 d occurs within
2be70 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 an.** explicit t
2be80 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 ransaction then
2be90 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 you should rollb
2bea0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 ack the transact
2beb0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f ion before.** co
2bec0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 ntinuing..**.**
2bed0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d ^[SQLITE_DONE] m
2bee0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 eans that the st
2bef0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 atement has fini
2bf00 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a shed executing.*
2bf10 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 * successfully.
2bf20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2bf30 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
2bf40 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 lled again on th
2bf50 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 is virtual.** ma
2bf60 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 chine without fi
2bf70 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c rst calling [sql
2bf80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f ite3_reset()] to
2bf90 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 reset the virtu
2bfa0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 al.** machine ba
2bfb0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
2bfc0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e l state..**.** ^
2bfd0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
2bfe0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
2bff0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
2c000 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 data, then [SQLI
2c010 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 TE_ROW].** is re
2c020 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 turned each time
2c030 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 a new row of da
2c040 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 ta is ready for
2c050 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 processing by th
2c060 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 e.** caller. The
2c070 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 values may be a
2c080 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 ccessed using th
2c090 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 e [column access
2c0a0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
2c0b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
2c0c0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 s called again t
2c0d0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e o retrieve the n
2c0e0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e ext row of data.
2c0f0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
2c100 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 ERROR] means tha
2c110 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 t a run-time err
2c120 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f or (such as a co
2c130 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c nstraint.** viol
2c140 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 ation) has occur
2c150 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 red. sqlite3_st
2c160 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ep() should not
2c170 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
2c180 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f on.** the VM. Mo
2c190 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d re information m
2c1a0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 ay be found by c
2c1b0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2c1c0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 errmsg()]..** ^W
2c1d0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 ith the legacy i
2c1e0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 nterface, a more
2c1f0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
2c200 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c code (for exampl
2c210 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e e,.** [SQLITE_IN
2c220 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 TERRUPT], [SQLIT
2c230 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 E_SCHEMA], [SQLI
2c240 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 TE_CORRUPT], and
2c250 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 so forth).** ca
2c260 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 n be obtained by
2c270 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2c280 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 3_reset()] on th
2c290 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2c2a0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 tatement]. ^In
2c2b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2c2c0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
2c2d0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
2c2e0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
2c2f0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
2c300 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
2c310 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
2c320 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2c330 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
2c340 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
2c350 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
2c360 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
2c370 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 ed on a [prepare
2c380 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
2c390 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 t has.** already
2c3a0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 been [sqlite3_f
2c3b0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
2c3c0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 zed] or on one t
2c3d0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 hat had.** previ
2c3e0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
2c3f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
2c400 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
2c410 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
2c420 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
2c430 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2c440 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2c450 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
2c460 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
2c470 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
2c480 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
2c490 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 ..**.** For all
2c4a0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
2c4b0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 te up to and inc
2c4c0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c luding 3.6.23.1,
2c4d0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 a call to.** [s
2c4e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2c4f0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 was required aft
2c500 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 er sqlite3_step(
2c510 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 ) returned anyth
2c520 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 ing.** other tha
2c530 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 n [SQLITE_ROW] b
2c540 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 efore any subseq
2c550 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 uent invocation
2c560 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 of.** sqlite3_st
2c570 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 ep(). Failure t
2c580 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 o reset the prep
2c590 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 ared statement u
2c5a0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 sing .** [sqlite
2c5b0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 3_reset()] would
2c5c0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 result in an [S
2c5d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 QLITE_MISUSE] re
2c5e0 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c turn from.** sql
2c5f0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 ite3_step(). Bu
2c600 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 t after version
2c610 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 3.6.23.1, sqlite
2c620 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 3_step() began.*
2c630 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 * calling [sqlit
2c640 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f e3_reset()] auto
2c650 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 matically in thi
2c660 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 s circumstance r
2c670 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 ather.** than re
2c680 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f turning [SQLITE_
2c690 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 MISUSE]. This i
2c6a0 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 s not considered
2c6b0 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 a compatibility
2c6c0 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 .** break becaus
2c6d0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f e any applicatio
2c6e0 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 n that ever rece
2c6f0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d ives an SQLITE_M
2c700 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 ISUSE error.** i
2c710 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 s broken by defi
2c720 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 nition. The [SQ
2c730 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 LITE_OMIT_AUTORE
2c740 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d SET] compile-tim
2c750 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 e option.** can
2c760 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f be used to resto
2c770 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 re the legacy be
2c780 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 havior..**.** <b
2c790 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 >Goofy Interface
2c7a0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 Alert:</b> In t
2c7b0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
2c7c0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ace, the sqlite3
2c7d0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 _step().** API a
2c7e0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 lways returns a
2c7f0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f generic error co
2c800 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f de, [SQLITE_ERRO
2c810 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e R], following an
2c820 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 y.** error other
2c830 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 than [SQLITE_BU
2c840 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f SY] and [SQLITE_
2c850 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 MISUSE]. You mu
2c860 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 st call.** [sqli
2c870 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
2c880 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2c890 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f e()] in order to
2c8a0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 find one of the
2c8b0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 .** specific [er
2c8c0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 ror codes] that
2c8d0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 better describes
2c8e0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 the error..** W
2c8f0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 e admit that thi
2c900 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 s is a goofy des
2c910 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 ign. The proble
2c920 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 m has been fixed
2c930 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 .** with the "v2
2c940 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 " interface. If
2c950 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c you prepare all
2c960 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 of your SQL sta
2c970 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 tements.** using
2c980 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
2c990 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2c9a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
2c9b0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 re16_v2()] inste
2c9c0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 ad.** of the leg
2c9d0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 acy [sqlite3_pre
2c9e0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
2c9f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2ca00 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a ] interfaces,.**
2ca10 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 then the more s
2ca20 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
2ca30 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e odes] are return
2ca40 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 ed directly.** b
2ca50 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
2ca60 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 . The use of th
2ca70 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2ca80 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e is recommended.
2ca90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2caa0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d step(sqlite3_stm
2cab0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2cac0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 3REF: Number of
2cad0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 columns in a res
2cae0 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 ult set.**.** ^T
2caf0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2cb00 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 count(P) interfa
2cb10 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
2cb20 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2cb30 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 in the.** curre
2cb40 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2cb50 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 sult set of [pre
2cb60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2cb70 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 P..** ^If prepa
2cb80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 red statement P
2cb90 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 does not have re
2cba0 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 sults ready to r
2cbb0 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 eturn.** (via ca
2cbc0 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 lls to the [sqli
2cbd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c te3_column_int |
2cbe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2cbf0 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 *()] of.** inter
2cc00 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 faces) then sqli
2cc10 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2cc20 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 ) returns 0..**
2cc30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2cc40 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
2cc50 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 ne also returns
2cc60 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 0 if P is a NULL
2cc70 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 pointer..** ^Th
2cc80 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2cc90 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
2cca0 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 returns 0 if the
2ccb0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2ccc0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
2ccd0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 ep](P) returned
2cce0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
2ccf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2cd00 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 a_count(P).** wi
2cd10 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 ll return non-ze
2cd20 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 ro if previous c
2cd30 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2cd40 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 step](P) returne
2cd50 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 d.** [SQLITE_ROW
2cd60 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 ], except in the
2cd70 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 case of the [PR
2cd80 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c AGMA incremental
2cd90 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 _vacuum].** wher
2cda0 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 e it always retu
2cdb0 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 rns zero since e
2cdc0 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 ach step of that
2cdd0 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 multi-step.** p
2cde0 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 ragma returns 0
2cdf0 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e columns of data.
2ce00 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2ce10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2ce20 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 _count()].*/.int
2ce30 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
2ce40 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
2ce50 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2ce60 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
2ce70 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
2ce80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
2ce90 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
2cea0 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e ^(Every value in
2ceb0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 SQLite has one
2cec0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e of five fundamen
2ced0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a tal datatypes:.*
2cee0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
2cef0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 > 64-bit signed
2cf00 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 integer.** <li>
2cf10 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 64-bit IEEE floa
2cf20 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
2cf30 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 r.** <li> string
2cf40 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a .** <li> BLOB.**
2cf50 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f <li> NULL.** </
2cf60 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ul>)^.**.** Thes
2cf70 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
2cf80 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
2cf90 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
2cfa0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
2cfb0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
2cfc0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
2cfd0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
2cfe0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
2cff0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
2d000 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
2d010 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
2d020 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
2d030 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
2d040 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
2d050 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
2d060 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
2d070 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
2d080 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
2d090 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
2d0a0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
2d0b0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
2d0c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
2d0d0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
2d0e0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
2d0f0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
2d100 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
2d110 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
2d120 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2d130 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
2d140 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
2d150 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
2d160 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2d170 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
2d180 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 m A Query.** KEY
2d190 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 WORDS: {column a
2d1a0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d ccess functions}
2d1b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
2d1c0 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 tines form the "
2d1d0 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 result set" inte
2d1e0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rface..**.** ^Th
2d1f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
2d200 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
2d210 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 about a single c
2d220 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 olumn of the cur
2d230 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 rent.** result r
2d240 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
2d250 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 ^In every case t
2d260 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2d270 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
2d280 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
2d290 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2d2a0 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
2d2b0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
2d2c0 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
2d2d0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
2d2e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
2d2f0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
2d300 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
2d310 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
2d320 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
2d330 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
2d340 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
2d350 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
2d360 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
2d370 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 urned. ^The left
2d380 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
2d390 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
2d3a0 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
2d3b0 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 * ^The number of
2d3c0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
2d3d0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 result can be de
2d3e0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a termined using.*
2d3f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2d400 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a n_count()]..**.*
2d410 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
2d420 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
2d430 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
2d440 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
2d450 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c or if the.** col
2d460 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 umn index is out
2d470 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 of range, the r
2d480 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
2d490 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ed..** These rou
2d4a0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 tines may only b
2d4b0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 e called when th
2d4c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
2d4d0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
2d4e0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
2d4f0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
2d500 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a OW] and neither.
2d510 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
2d520 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 t()] nor [sqlite
2d530 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 3_finalize()] ha
2d540 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 ve been called s
2d550 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 ubsequently..**
2d560 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 If any of these
2d570 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
2d580 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
2d590 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
2d5a0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
2d5b0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
2d5c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2d5d0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a has returned.**
2d5e0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
2d5f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
2d600 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 W], the results
2d610 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
2d620 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 * If [sqlite3_st
2d630 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
2d640 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
2d650 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2d660 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 )].** are called
2d670 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e from a differen
2d680 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 t thread while a
2d690 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
2d6a0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 ines.** are pend
2d6b0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
2d6c0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2d6d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2d6e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2d6f0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ype() routine re
2d700 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 turns the.** [SQ
2d710 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
2d720 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
2d730 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
2d740 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
2d750 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
2d760 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
2d770 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
2d780 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
2d790 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
2d7a0 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
2d7b0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
2d7c0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
2d7d0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a LL]. The value.
2d7e0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
2d7f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2d800 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 pe() is only mea
2d810 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 ningful if no ty
2d820 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e pe.** conversion
2d830 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 s have occurred
2d840 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c as described bel
2d850 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 ow. After a typ
2d860 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a e conversion,.**
2d870 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
2d880 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2d890 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
2d8a0 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 undefined. Futu
2d8b0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f re.** versions o
2d8c0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 f SQLite may cha
2d8d0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 nge the behavior
2d8e0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 of sqlite3_colu
2d8f0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c mn_type().** fol
2d900 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f lowing a type co
2d910 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
2d920 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2d930 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
2d940 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
2d950 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2d960 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
2d970 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
2d980 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2d990 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
2d9a0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
2d9b0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
2d9c0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
2d9d0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2d9e0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
2d9f0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
2da00 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
2da10 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
2da20 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
2da30 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2da40 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
2da50 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
2da60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2da70 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
2da80 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
2da90 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
2daa0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
2dab0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2dac0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2dad0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2dae0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2daf0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
2db00 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
2db10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2db20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
2db30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2db40 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2db50 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 UTF-16 string th
2db60 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
2db70 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a olumn_bytes16().
2db80 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
2db90 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2dba0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
2dbb0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
2dbc0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2dbd0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
2dbe0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
2dbf0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2dc00 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2dc10 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2dc20 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 16 and then retu
2dc30 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2dc40 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
2dc50 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2dc60 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
2dc70 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2dc80 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 n_bytes16() uses
2dc90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
2dca0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
2dcb0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
2dcc0 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e o a UTF-16 strin
2dcd0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
2dce0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2dcf0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
2dd00 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
2dd10 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
2dd20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2dd30 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 umn_bytes16() re
2dd40 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
2dd50 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 * ^The values re
2dd60 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2dd70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2dd80 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 )] and .** [sqli
2dd90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2dda0 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 16()] do not inc
2ddb0 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
2ddc0 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 rminators at the
2ddd0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
2dde0 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 tring. ^For cla
2ddf0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 rity: the values
2de00 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2de10 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2de20 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 bytes()] and [sq
2de30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2de40 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 es16()] are the
2de50 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
2de60 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
2de70 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2de80 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
2de90 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 **.** ^Strings r
2dea0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2deb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2dec0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2ded0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a umn_text16(),.**
2dee0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 even empty stri
2def0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 ngs, are always
2df00 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
2df10 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a ^The return.**
2df20 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
2df30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2df40 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
2df50 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 gth BLOB is a NU
2df60 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
2df70 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 * ^The object re
2df80 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2df90 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2dfa0 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
2dfb0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2dfc0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
2dfd0 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 An unprotected
2dfe0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2dff0 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ject.** may only
2e000 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 be used with [s
2e010 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
2e020 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
2e030 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
2e040 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e ]..** If the [un
2e050 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2e060 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
2e070 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
2e080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2e090 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 alue()] is used
2e0a0 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 in any other way
2e0b0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c , including call
2e0c0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 s.** to routines
2e0d0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 like [sqlite3_v
2e0e0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 alue_int()], [sq
2e0f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2e100 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
2e110 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
2e120 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 )], then the beh
2e130 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
2e140 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
2e150 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 routines attempt
2e160 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
2e170 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 value where appr
2e180 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a opriate. ^For.*
2e190 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 * example, if th
2e1a0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
2e1b0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f sentation is FLO
2e1c0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 AT and a text re
2e1d0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 sult.** is reque
2e1e0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 sted, [sqlite3_s
2e1f0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 nprintf()] is us
2e200 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
2e210 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 perform the.**
2e220 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d conversion autom
2e230 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 atically. ^(The
2e240 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 following table
2e250 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e details the con
2e260 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 versions.** that
2e270 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a are applied:.**
2e280 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2e290 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
2e2a0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 r="1">.** <tr><t
2e2b0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 h> Internal<br>T
2e2c0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 ype <th> Request
2e2d0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 ed<br>Type <th>
2e2e0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a Conversion.**.*
2e2f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2e300 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
2e310 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2e320 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 s 0.** <tr><td>
2e330 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 NULL <td> F
2e340 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 LOAT <td> Res
2e350 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 ult is 0.0.** <t
2e360 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
2e370 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
2e380 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 td> Result is a
2e390 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
2e3a0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
2e3b0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
2e3c0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
2e3d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
2e3e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
2e3f0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 ER <td> FLOAT
2e400 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2e410 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 from integer to
2e420 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
2e430 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
2e440 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
2e450 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
2e460 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a f the integer.**
2e470 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
2e480 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 R <td> BLOB
2e490 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 <td> Same as I
2e4a0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 NTEGER->TEXT.**
2e4b0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
2e4c0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
2e4d0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
2e4e0 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c INTEGER.** <tr><
2e4f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
2e500 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2e510 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
2e520 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a of the float.**
2e530 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
2e540 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
2e550 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
2e560 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 BLOB.** <tr><td
2e570 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
2e580 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b INTEGER <td> [
2e590 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 CAST] to INTEGER
2e5a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
2e5b0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 XT <td> FLOA
2e5c0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d T <td> [CAST]
2e5d0 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e to REAL.** <tr>
2e5e0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
2e5f0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
2e600 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c > No change.** <
2e610 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
2e620 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
2e630 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 <td> [CAST] to I
2e640 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 NTEGER.** <tr><t
2e650 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
2e660 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2e670 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a [CAST] to REAL.*
2e680 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
2e690 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
2e6a0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 <td> Add a ze
2e6b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 ro terminator if
2e6c0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 needed.** </tab
2e6d0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 le>.** </blockqu
2e6e0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ote>)^.**.** The
2e6f0 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b table above mak
2e700 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 es reference to
2e710 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
2e720 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f ry functions ato
2e730 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 i().** and atof(
2e740 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ). SQLite does
2e750 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 not really use t
2e760 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
2e770 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f It has its.** o
2e780 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e wn equivalent in
2e790 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e ternal routines.
2e7a0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 The atoi() and
2e7b0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 atof() names ar
2e7c0 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 e.** used in the
2e7d0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 table for brevi
2e7e0 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 ty and because t
2e7f0 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 hey are familiar
2e800 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 to most.** C pr
2e810 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a ogrammers..**.**
2e820 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 Note that when
2e830 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 type conversions
2e840 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 occur, pointers
2e850 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 returned by pri
2e860 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 or.** calls to s
2e870 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
2e880 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f ob(), sqlite3_co
2e890 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 lumn_text(), and
2e8a0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 /or.** sqlite3_c
2e8b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d olumn_text16() m
2e8c0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 ay be invalidate
2e8d0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 d..** Type conve
2e8e0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 rsions and point
2e8f0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 er invalidations
2e900 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
2e910 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
2e920 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 cases:.**.** <u
2e930 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 l>.** <li> The i
2e940 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2e950 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c s a BLOB and sql
2e960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2e970 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
2e980 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2e990 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
2e9a0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 A zero-termina
2e9b0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 tor might.**
2e9c0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 need to be add
2e9d0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 ed to the string
2e9e0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
2e9f0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
2ea00 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 nt is UTF-8 text
2ea10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2ea20 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 umn_bytes16() or
2ea30 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
2ea40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2ea50 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
2ea60 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
2ea70 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
2ea80 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c to UTF-16.</l
2ea90 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
2eaa0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2eab0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e s UTF-16 text an
2eac0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2ead0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 _bytes() or.**
2eae0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
2eaf0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c mn_text() is cal
2eb00 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
2eb10 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
2eb20 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
2eb30 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f TF-8.</li>.** </
2eb40 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 ul>.**.** ^Conve
2eb50 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 rsions between U
2eb60 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d TF-16be and UTF-
2eb70 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 16le are always
2eb80 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e done in place an
2eb90 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 d do.** not inva
2eba0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 lidate a prior p
2ebb0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f ointer, though o
2ebc0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e f course the con
2ebd0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 tent of the buff
2ebe0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 er.** that the p
2ebf0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 rior pointer ref
2ec00 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 erences will hav
2ec10 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e e been modified.
2ec20 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a Other kinds.**
2ec30 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 of conversion a
2ec40 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 re done in place
2ec50 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 when it is poss
2ec60 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 ible, but someti
2ec70 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 mes they.** are
2ec80 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 not possible and
2ec90 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 in those cases
2eca0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 prior pointers a
2ecb0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a re invalidated..
2ecc0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 **.** The safest
2ecd0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 and easiest to
2ece0 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 remember policy
2ecf0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 is to invoke the
2ed00 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 se routines.** i
2ed10 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c n one of the fol
2ed20 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a lowing ways:.**.
2ed30 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e ** <ul>.** <li>
2ed40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2ed50 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 ext() followed b
2ed60 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
2ed70 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
2ed80 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
2ed90 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c lumn_blob() foll
2eda0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
2edb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f column_bytes()</
2edc0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 li>.** <li>sqli
2edd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2ede0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6() followed by
2edf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2ee00 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a ytes16()</li>.**
2ee10 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
2ee20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
2ee30 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
2ee40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2ee50 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 (),.** sqlite3_c
2ee60 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 olumn_blob(), or
2ee70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2ee80 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
2ee90 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
2eea0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 lt.** into the d
2eeb0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 esired format, t
2eec0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
2eed0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2eee0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
2eef0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2ef00 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a to find the siz
2ef10 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
2ef20 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
2ef30 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 ls.** to sqlite3
2ef40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
2ef50 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
2ef60 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c _blob() with cal
2ef70 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
2ef80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2ef90 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 ), and do not mi
2efa0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
2efb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
2efc0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 ().** with calls
2efd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
2efe0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a mn_bytes()..**.*
2eff0 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 * ^The pointers
2f000 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
2f010 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
2f020 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
2f030 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
2f040 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
2f050 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
2f060 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
2f070 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
2f080 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2f090 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e )] is called. ^
2f0a0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 The memory space
2f0b0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 used to hold st
2f0c0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f rings.** and BLO
2f0d0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f Bs is freed auto
2f0e0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c matically. Do <
2f0f0 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 b>not</b> pass t
2f100 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
2f110 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 rned.** from [sq
2f120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2f130 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 b()], [sqlite3_c
2f140 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 olumn_text()], e
2f150 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c tc. into.** [sql
2f160 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
2f170 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 .** ^(If a memor
2f180 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
2f190 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
2f1a0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 the evaluation
2f1b0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
2f1c0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 se routines, a d
2f1d0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 efault value is
2f1e0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 returned. The d
2f1f0 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 efault value.**
2f200 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e is either the in
2f210 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f teger 0, the flo
2f220 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
2f230 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c er 0.0, or a NUL
2f240 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 L.** pointer. S
2f250 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
2f260 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
2f270 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 ode()] will retu
2f280 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f rn.** [SQLITE_NO
2f290 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 MEM].)^.*/.const
2f2a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2f2b0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 olumn_blob(sqlit
2f2c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2f2d0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
2f2e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 _column_bytes(sq
2f2f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2f300 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
2f310 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2f320 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2f330 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 , int iCol);.dou
2f340 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ble sqlite3_colu
2f350 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 mn_double(sqlite
2f360 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2f370 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2f380 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 column_int(sqlit
2f390 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2f3a0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ol);.sqlite3_int
2f3b0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 64 sqlite3_colum
2f3c0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f n_int64(sqlite3_
2f3d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2f3e0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
2f3f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
2f400 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 olumn_text(sqlit
2f410 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2f420 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 ol);.const void
2f430 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2f440 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
2f450 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2f460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2f470 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 umn_type(sqlite3
2f480 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2f490 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 );.sqlite3_value
2f4a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2f4b0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
2f4c0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2f4d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2f4e0 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 : Destroy A Prep
2f4f0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
2f500 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bject.**.** ^The
2f510 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2f520 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
2f530 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 called to delete
2f540 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2f550 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 tement]..** ^If
2f560 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
2f570 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 evaluation of th
2f580 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f e statement enco
2f590 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 untered no error
2f5a0 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 s.** or if the s
2f5b0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 tatement is neve
2f5c0 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 r been evaluated
2f5d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 , then sqlite3_f
2f5e0 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e inalize() return
2f5f0 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 s.** SQLITE_OK.
2f600 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
2f610 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 cent evaluation
2f620 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 of statement S f
2f630 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 ailed, then.** s
2f640 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2f650 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 S) returns the a
2f660 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
2f670 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 r code] or.** [e
2f680 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
2f690 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
2f6a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2f6b0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 (S) routine can
2f6c0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
2f6d0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a point during.**
2f6e0 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 the life cycle
2f6f0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 of [prepared sta
2f700 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 tement] S:.** be
2f710 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 fore statement S
2f720 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 is ever evaluat
2f730 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 ed, after.** one
2f740 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 or more calls t
2f750 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
2f760 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e ()], or after an
2f770 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 y call.** to [sq
2f780 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 lite3_step()] re
2f790 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
2f7a0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 her or not the s
2f7b0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 tatement has.**
2f7c0 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 completed execut
2f7d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f ion..**.** ^Invo
2f7e0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e king sqlite3_fin
2f7f0 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c alize() on a NUL
2f800 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 L pointer is a h
2f810 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
2f820 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
2f830 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 tion must finali
2f840 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 ze every [prepar
2f850 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
2f860 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a order to avoid.
2f870 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b ** resource leak
2f880 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 s. It is a grie
2f890 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 vous error for t
2f8a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 he application t
2f8b0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 o try to use.**
2f8c0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
2f8d0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 ment after it ha
2f8e0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 s been finalized
2f8f0 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 . Any use of a
2f900 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
2f910 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 ement after it h
2f920 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
2f930 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 d can result in
2f940 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a undefined and.**
2f950 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 undesirable beh
2f960 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 avior such as se
2f970 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 gfaults and heap
2f980 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a corruption..*/.
2f990 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 int sqlite3_fina
2f9a0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d lize(sqlite3_stm
2f9b0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2f9c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
2f9d0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 t A Prepared Sta
2f9e0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
2f9f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2fa00 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
2fa10 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
2fa20 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
2fa30 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
2fa40 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
2fa50 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
2fa60 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
2fa70 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 xecuted..** ^Any
2fa80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
2fa90 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
2faa0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
2fab0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
2fac0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
2fad0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
2fae0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
2faf0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
2fb00 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
2fb10 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
2fb20 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
2fb30 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
2fb40 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
2fb50 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
2fb60 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 face resets the
2fb70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2fb80 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 ent] S.** back t
2fb90 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
2fba0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
2fbb0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
2fbc0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
2fbd0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
2fbe0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
2fbf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2fc00 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
2fc10 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
2fc20 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
2fc30 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
2fc40 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
2fc50 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
2fc60 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 alled on S,.** t
2fc70 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
2fc80 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
2fc90 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
2fca0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
2fcb0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
2fcc0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
2fcd0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
2fce0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2fcf0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
2fd00 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 rror, then.** [s
2fd10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
2fd20 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
2fd30 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
2fd40 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
2fd50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2fd60 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
2fd70 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
2fd80 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 e values.** of a
2fd90 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
2fda0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
2fdb0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
2fdc0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
2fdd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
2fde0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
2fdf0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2fe00 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
2fe10 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
2fe20 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b L Functions.** K
2fe30 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
2fe40 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
2fe50 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
2fe60 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
2fe70 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2fe80 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
2fe90 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
2fea0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2feb0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 tions}.**.** ^Th
2fec0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 ese functions (c
2fed0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 ollectively know
2fee0 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 n as "function c
2fef0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
2ff00 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 ").** are used t
2ff10 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 o add SQL functi
2ff20 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
2ff30 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 s or to redefine
2ff40 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
2ff50 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c of existing SQL
2ff60 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
2ff70 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f gregates. The o
2ff80 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 nly differences
2ff90 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 between.** these
2ffa0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 routines are th
2ffb0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 e text encoding
2ffc0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 expected for.**
2ffd0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
2ffe0 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f eter (the name o
2fff0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 f the function b
30000 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a eing created).**
30010 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 and the presenc
30020 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 e or absence of
30030 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c a destructor cal
30040 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 lback for.** the
30050 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
30060 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a a pointer..**.**
30070 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
30080 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 meter is the [da
30090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
300a0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 n] to which the
300b0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
300c0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 is to be added.
300d0 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 ^If an applicat
300e0 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 ion uses more th
300f0 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a an one database.
30100 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ** connection th
30110 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 en application-d
30120 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
30130 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 ions must be add
30140 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 ed.** to each da
30150 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
30160 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a n separately..**
30170 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
30180 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
30190 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c name of the SQL
301a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
301b0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 created or.** re
301c0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c defined. ^The l
301d0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d ength of the nam
301e0 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 e is limited to
301f0 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 255 bytes in a U
30200 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e TF-8.** represen
30210 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 tation, exclusiv
30220 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 e of the zero-te
30230 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 rminator. ^Note
30240 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a that the name.*
30250 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 * length limit i
30260 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 s in UTF-8 bytes
30270 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 , not characters
30280 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 nor UTF-16 byte
30290 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 s. .** ^Any att
302a0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
302b0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
302c0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
302d0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
302e0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 SQLITE_MISUSE] b
302f0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a eing returned..*
30300 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
30310 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 parameter (nArg)
30320 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
30330 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
30340 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
30350 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
30360 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 gate takes. ^If
30370 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 this parameter i
30380 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 s -1, then the S
30390 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
303a0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 * aggregate may
303b0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 take any number
303c0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 of arguments bet
303d0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c ween 0 and the l
303e0 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b imit.** set by [
303f0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b sqlite3_limit]([
30400 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
30410 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 CTION_ARG]). If
30420 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
30430 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 rameter is less
30440 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 than -1 or great
30450 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e er than 127 then
30460 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
30470 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
30480 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
30490 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 parameter, eTex
304a0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 tRep, specifies
304b0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f what.** [SQLITE_
304c0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f UTF8 | text enco
304d0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 ding] this SQL f
304e0 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 unction prefers
304f0 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d for.** its param
30500 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c eters. The appl
30510 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 ication should s
30520 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 et this paramete
30530 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f r to.** [SQLITE_
30540 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 UTF16LE] if the
30550 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
30560 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 ntation invokes
30570 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
30580 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f ue_text16le()] o
30590 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b n an input, or [
305a0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 SQLITE_UTF16BE]
305b0 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d if the.** implem
305c0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 entation invokes
305d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
305e0 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 text16be()] on a
305f0 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b n input, or.** [
30600 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 SQLITE_UTF16] if
30610 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
30620 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 text16()] is use
30630 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 d, or [SQLITE_UT
30640 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 F8].** otherwise
30650 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c . ^The same SQL
30660 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 function may be
30670 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 registered mult
30680 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 iple times using
30690 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 .** different pr
306a0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
306b0 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 odings, with dif
306c0 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 ferent implement
306d0 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 ations for.** ea
306e0 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 ch encoding..**
306f0 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 ^When multiple i
30700 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
30710 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
30720 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c ion are availabl
30730 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c e, SQLite.** wil
30740 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 l pick the one t
30750 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 hat involves the
30760 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 least amount of
30770 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e data conversion
30780 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
30790 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 rth parameter ma
307a0 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 y optionally be
307b0 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 ORed with [SQLIT
307c0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d E_DETERMINISTIC]
307d0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 .** to signal th
307e0 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 at the function
307f0 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 will always retu
30800 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 rn the same resu
30810 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 lt given.** the
30820 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 same inputs with
30830 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 in a single SQL
30840 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 statement. Most
30850 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
30860 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 re.** determinis
30870 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d tic. The built-
30880 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 in [random()] SQ
30890 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e L function is an
308a0 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a example of a.**
308b0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 function that i
308c0 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 s not determinis
308d0 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 tic. The SQLite
308e0 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 query planner i
308f0 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 s able to.** per
30900 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 form additional
30910 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e optimizations on
30920 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 deterministic f
30930 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 unctions, so use
30940 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 .** of the [SQLI
30950 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 TE_DETERMINISTIC
30960 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d ] flag is recomm
30970 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 ended where poss
30980 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ible..**.** ^(Th
30990 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 e fifth paramete
309a0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 r is an arbitrar
309b0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 y pointer. The
309c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
309d0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f f the.** functio
309e0 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 n can gain acces
309f0 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 s to this pointe
30a00 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 r using [sqlite3
30a10 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e _user_data()].)^
30a20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 .**.** ^The sixt
30a30 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 h, seventh and e
30a40 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 ighth parameters
30a50 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 , xFunc, xStep a
30a60 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a nd xFinal, are.*
30a70 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d * pointers to C-
30a80 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f language functio
30a90 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ns that implemen
30aa0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
30ab0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
30ac0 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 te. ^A scalar SQ
30ad0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
30ae0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
30af0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 ation of the xFu
30b00 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f nc.** callback o
30b10 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nly; NULL pointe
30b20 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 rs must be passe
30b30 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 d as the xStep a
30b40 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 nd xFinal.** par
30b50 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 ameters. ^An agg
30b60 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
30b70 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
30b80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
30b90 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 f xStep.** and x
30ba0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 Final and NULL p
30bb0 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 ointer must be p
30bc0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e assed for xFunc.
30bd0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 ^To delete an e
30be0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 xisting.** SQL f
30bf0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
30c00 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 gate, pass NULL
30c10 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c pointers for all
30c20 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a three function.
30c30 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a ** callbacks..**
30c40 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e .** ^(If the nin
30c50 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
30c60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
30c70 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 unction_v2() is
30c80 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 not NULL,.** the
30c90 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 n it is destruct
30ca0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 or for the appli
30cb0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
30cc0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 ter. .** The des
30cd0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b tructor is invok
30ce0 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 ed when the func
30cf0 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c tion is deleted,
30d00 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 either by being
30d10 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f .** overloaded o
30d20 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 r when the datab
30d30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
30d40 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 loses.)^.** ^The
30d50 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 destructor is a
30d60 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 lso invoked if t
30d70 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 he call to.** sq
30d80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
30d90 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 ction_v2() fails
30da0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 ..** ^When the d
30db0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 estructor callba
30dc0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 ck of the tenth
30dd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 parameter is inv
30de0 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 oked, it.** is p
30df0 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 assed a single a
30e00 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
30e10 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 a copy of the a
30e20 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 pplication data
30e30 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 .** pointer whic
30e40 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 h was the fifth
30e50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
30e60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
30e70 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a tion_v2()..**.**
30e80 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 ^It is permitte
30e90 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 d to register mu
30ea0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
30eb0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
30ec0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 me.** functions
30ed0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 with the same na
30ee0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 me but with eith
30ef0 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d er differing num
30f00 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d bers of.** argum
30f10 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e ents or differin
30f20 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 g preferred text
30f30 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 encodings. ^SQ
30f40 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a Lite will use.**
30f50 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
30f60 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c ion that most cl
30f70 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 osely matches th
30f80 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 e way in which t
30f90 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 he.** SQL functi
30fa0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 on is used. ^A
30fb0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
30fc0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e ntation with a n
30fd0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e on-negative.** n
30fe0 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 Arg parameter is
30ff0 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 a better match
31000 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
31010 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
31020 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 ith.** a negativ
31030 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 e nArg. ^A func
31040 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 tion where the p
31050 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
31060 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 coding.** matche
31070 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 s the database e
31080 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 ncoding is a bet
31090 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 ter.** match tha
310a0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
310b0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
310c0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a is different. .
310d0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 ** ^A function w
310e0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
310f0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 g difference is
31100 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 between UTF16le
31110 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 and UTF16be.** i
31120 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 s a closer match
31130 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
31140 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
31150 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
31160 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 s.** between UTF
31170 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 8 and UTF16..**.
31180 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e ** ^Built-in fun
31190 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 ctions may be ov
311a0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 erloaded by new
311b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
311c0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a ned functions..*
311d0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 *.** ^An applica
311e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
311f0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
31200 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 ed to call other
31210 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
31220 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c faces. However,
31230 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 such calls must
31240 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 not.** close th
31250 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
31260 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 ction nor finali
31270 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 ze or reset the
31280 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
31290 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 ement in which t
312a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 he function is r
312b0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 unning..*/.int s
312c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
312d0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 nction(. sqlite
312e0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 3 *db,. const c
312f0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 har *zFunctionNa
31300 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
31310 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
31320 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
31330 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
31340 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
31350 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
31360 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
31370 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
31380 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
31390 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
313a0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
313b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
313c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 ;.int sqlite3_cr
313d0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
313e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
313f0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 const void *zF
31400 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
31410 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
31420 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
31430 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
31440 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
31450 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
31460 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
31470 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
31480 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
31490 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
314a0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
314b0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
314c0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 ntext*).);.int s
314d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
314e0 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c nction_v2(. sql
314f0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
31500 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
31510 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
31520 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
31530 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
31540 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
31550 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
31560 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
31570 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
31580 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
31590 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
315a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
315b0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
315c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
315d0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 ),. void(*xDest
315e0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a roy)(void*).);..
315f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31600 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a Text Encodings.*
31610 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
31620 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 ant define integ
31630 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 er codes that re
31640 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 present the vari
31650 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f ous.** text enco
31660 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 dings supported
31670 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 by SQLite..*/.#d
31680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
31690 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 8 1.#d
316a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
316b0 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 16LE 2.#d
316c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
316d0 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 16BE 3.#d
316e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
316f0 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 16 4
31700 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 /* Use native b
31710 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 yte order */.#de
31720 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 fine SQLITE_ANY
31730 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 5
31740 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f /* Deprecated */
31750 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
31760 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 UTF16_ALIGNED 8
31770 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 /* sqlite3_c
31780 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 reate_collation
31790 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 only */../*.** C
317a0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f API3REF: Functio
317b0 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 n Flags.**.** Th
317c0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 ese constants ma
317d0 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 y be ORed togeth
317e0 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 er with the .**
317f0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 [SQLITE_UTF8 | p
31800 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
31810 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 coding] as the f
31820 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a ourth argument.*
31830 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
31840 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
31850 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 , [sqlite3_creat
31860 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c e_function16()],
31870 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
31880 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
31890 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e v2()]..*/.#defin
318a0 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 e SQLITE_DETERMI
318b0 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a NISTIC 0x800.
318c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
318d0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 Deprecated Func
318e0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 tions.** DEPRECA
318f0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TED.**.** These
31900 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 functions are [d
31910 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 eprecated]. In
31920 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 order to maintai
31930 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 n.** backwards c
31940 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
31950 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 h older code, th
31960 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f ese functions co
31970 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 ntinue .** to be
31980 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 supported. How
31990 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 ever, new applic
319a0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 ations should av
319b0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f oid.** the use o
319c0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
319d0 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f s. To help enco
319e0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 urage people to
319f0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 avoid.** using t
31a00 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 hese functions,
31a10 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 we are not going
31a20 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 to tell you wha
31a30 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 t they do..*/.#i
31a40 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 fndef SQLITE_OMI
31a50 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c T_DEPRECATED.SQL
31a60 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
31a70 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 nt sqlite3_aggre
31a80 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 gate_count(sqlit
31a90 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
31aa0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
31ab0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 int sqlite3_expi
31ac0 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 red(sqlite3_stmt
31ad0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 *);.SQLITE_DEPRE
31ae0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
31af0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 3_transfer_bindi
31b00 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
31b10 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a *, sqlite3_stmt*
31b20 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
31b30 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
31b40 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 _global_recover(
31b50 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 void);.SQLITE_DE
31b60 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 PRECATED void sq
31b70 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 lite3_thread_cle
31b80 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 anup(void);.SQLI
31b90 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
31ba0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 t sqlite3_memory
31bb0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 _alarm(void(*)(v
31bc0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
31bd0 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 64,int),.
31be0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
31bf0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
31c00 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
31c10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
31c20 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 aining SQL Funct
31c30 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 ion Parameter Va
31c40 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 lues.**.** The C
31c50 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d -language implem
31c60 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 entation of SQL
31c70 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
31c80 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a gregates uses.**
31c90 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 this set of int
31ca0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 erface routines
31cb0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 to access the pa
31cc0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f rameter values o
31cd0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f n.** the functio
31ce0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a n or aggregate..
31cf0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 **.** The xFunc
31d00 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 (for scalar func
31d10 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 tions) or xStep
31d20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 (for aggregates)
31d30 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
31d40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
31d50 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
31d60 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
31d70 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
31d80 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 ** define callba
31d90 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 cks that impleme
31da0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
31db0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
31dc0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 tes..** The 3rd
31dd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
31de0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 se callbacks is
31df0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
31e00 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 ters to.** [prot
31e10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
31e20 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 lue] objects. T
31e30 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c here is one [sql
31e40 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
31e50 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 ct for.** each p
31e60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
31e70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 SQL function. T
31e80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
31e90 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 e used to.** ext
31ea0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d ract values from
31eb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
31ec0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
31ed0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
31ee0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 es work only wit
31ef0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c h [protected sql
31f00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
31f10 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 cts..** Any atte
31f20 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 mpt to use these
31f30 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 routines on an
31f40 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
31f50 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f ite3_value].** o
31f60 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e bject results in
31f70 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
31f80 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ior..**.** ^Thes
31f90 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
31fa0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f just like the co
31fb0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c rresponding [col
31fc0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
31fd0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 ions].** except
31fe0 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 that these rout
31ff0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 ines take a sing
32000 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 le [protected sq
32010 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
32020 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 ect.** pointer i
32030 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c nstead of a [sql
32040 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e ite3_stmt*] poin
32050 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 ter and an integ
32060 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 er column number
32070 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
32080 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
32090 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 6() interface ex
320a0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 tracts a UTF-16
320b0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 string.** in the
320c0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 native byte-ord
320d0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d er of the host m
320e0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a achine. ^The.**
320f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
32100 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 ext16be() and sq
32110 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
32120 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 16le() interface
32130 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 s.** extract UTF
32140 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 -16 strings as b
32150 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 ig-endian and li
32160 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 ttle-endian resp
32170 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ectively..**.**
32180 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^(The sqlite3_va
32190 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
321a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
321b0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a empts to apply.*
321c0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 * numeric affini
321d0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e ty to the value.
321e0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 This means tha
321f0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a t an attempt is.
32200 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 ** made to conve
32210 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 rt the value to
32220 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c an integer or fl
32230 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 oating point. I
32240 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 f.** such a conv
32250 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 ersion is possib
32260 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 le without loss
32270 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 of information (
32280 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 in other.** word
32290 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 s, if the value
322a0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 is a string that
322b0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 looks like a nu
322c0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 mber).** then th
322d0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 e conversion is
322e0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 performed. Othe
322f0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 rwise no convers
32300 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 ion occurs..** T
32310 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 he [SQLITE_INTEG
32320 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 ER | datatype] a
32330 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 fter conversion
32340 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a is returned.)^.*
32350 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 *.** Please pay
32360 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e particular atten
32370 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 tion to the fact
32380 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 that the pointe
32390 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 r returned.** fr
323a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 om [sqlite3_valu
323b0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 e_blob()], [sqli
323c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
323d0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ], or.** [sqlite
323e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
323f0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 ] can be invalid
32400 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 ated by a subseq
32410 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 uent call to.**
32420 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
32430 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ytes()], [sqlite
32440 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
32450 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
32460 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
32470 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
32480 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a _text16()]..**.*
32490 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
324a0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
324b0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
324c0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 read as.** the S
324d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 QL function that
324e0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 supplied the [s
324f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 qlite3_value*] p
32500 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f arameters..*/.co
32510 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
32520 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 3_value_blob(sql
32530 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
32540 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
32550 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 bytes(sqlite3_va
32560 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
32570 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 e3_value_bytes16
32580 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
32590 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 ;.double sqlite3
325a0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 _value_double(sq
325b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
325c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
325d0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c _int(sqlite3_val
325e0 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e ue*);.sqlite3_in
325f0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 t64 sqlite3_valu
32600 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f e_int64(sqlite3_
32610 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 value*);.const u
32620 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 nsigned char *sq
32630 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
32640 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
32650 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
32660 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
32670 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
32680 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a *);.const void *
32690 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
326a0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 xt16le(sqlite3_v
326b0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f alue*);.const vo
326c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
326d0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 e_text16be(sqlit
326e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
326f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 sqlite3_value_ty
32700 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
32710 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
32720 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 value_numeric_ty
32730 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
32740 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
32750 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 REF: Obtain Aggr
32760 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 egate Function C
32770 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 ontext.**.** Imp
32780 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
32790 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
327a0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 nctions use this
327b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 .** routine to a
327c0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 llocate memory f
327d0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 or storing their
327e0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 state..**.** ^T
327f0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 he first time th
32800 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 e sqlite3_aggreg
32810 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
32820 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c routine is call
32830 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 ed .** for a par
32840 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 ticular aggregat
32850 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 e function, SQLi
32860 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 te.** allocates
32870 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 N of memory, zer
32880 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d oes out that mem
32890 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 ory, and returns
328a0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
328b0 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e the new memory.
328c0 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 ^On second and
328d0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
328e0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 to.** sqlite3_a
328f0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
32900 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 () for the same
32910 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
32920 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 on instance,.**
32930 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 the same buffer
32940 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 is returned. Sq
32950 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
32960 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 context() is nor
32970 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 mally.** called
32980 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e once for each in
32990 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 vocation of the
329a0 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 xStep callback a
329b0 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c nd then one.** l
329c0 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 ast time when th
329d0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 e xFinal callbac
329e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e k is invoked. ^
329f0 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 (When no rows ma
32a00 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 tch.** an aggreg
32a10 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 ate query, the x
32a20 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 Step() callback
32a30 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 of the aggregate
32a40 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 function.** imp
32a50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e lementation is n
32a60 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 ever called and
32a70 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c xFinal() is call
32a80 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e ed exactly once.
32a90 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 .** In those cas
32aa0 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 es, sqlite3_aggr
32ab0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
32ac0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 might be called
32ad0 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 for the.** first
32ae0 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 time from withi
32af0 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a n xFinal().)^.**
32b00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
32b10 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
32b20 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 xt(C,N) routine
32b30 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
32b40 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 ointer .** when
32b50 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 first called if
32b60 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f N is less than o
32b70 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 r equal to zero
32b80 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a or if a memory.*
32b90 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 * allocate error
32ba0 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e occurs..**.** ^
32bb0 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 (The amount of s
32bc0 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 pace allocated b
32bd0 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 y sqlite3_aggreg
32be0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
32bf0 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 is.** determine
32c00 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d d by the N param
32c10 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 eter on first su
32c20 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 ccessful call.
32c30 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 Changing the.**
32c40 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 value of N in su
32c50 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f bsequent call to
32c60 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
32c70 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 te_context() wit
32c80 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 hin.** the same
32c90 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
32ca0 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c on instance will
32cb0 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 not resize the
32cc0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
32cd0 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 tion.)^ Within
32ce0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 the xFinal callb
32cf0 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f ack, it is custo
32d00 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e mary to set.** N
32d10 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 =0 in calls to s
32d20 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
32d30 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f _context(C,N) so
32d40 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 that no .** poi
32d50 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c ntless memory al
32d60 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e locations occur.
32d70 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 .**.** ^SQLite a
32d80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 utomatically fre
32d90 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c es the memory al
32da0 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 located by .** s
32db0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
32dc0 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 _context() when
32dd0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 the aggregate qu
32de0 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a ery concludes..*
32df0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 *.** The first p
32e00 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 arameter must be
32e10 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
32e20 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 * [sqlite3_conte
32e30 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f xt | SQL functio
32e40 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 n context] that
32e50 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 is the first par
32e60 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ameter.** to the
32e70 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c xStep or xFinal
32e80 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e callback routin
32e90 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 e that implement
32ea0 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a s the aggregate.
32eb0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a ** function..**.
32ec0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
32ed0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
32ee0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
32ef0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
32f00 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 the aggregate SQ
32f10 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
32f20 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a nning..*/.void *
32f30 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
32f40 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 e_context(sqlite
32f50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
32f60 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 nBytes);../*.**
32f70 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 CAPI3REF: User D
32f80 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e ata For Function
32f90 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
32fa0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 ite3_user_data()
32fb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
32fc0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 ns a copy of.**
32fd0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 the pointer that
32fe0 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 was the pUserDa
32ff0 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 ta parameter (th
33000 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 e 5th parameter)
33010 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
33020 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
33030 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
33040 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
33050 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
33060 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
33070 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
33080 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
33090 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
330a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ion..**.** This
330b0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
330c0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
330d0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
330e0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c hich.** the appl
330f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
33100 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
33110 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ing..*/.void *sq
33120 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
33130 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
33150 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
33160 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 nection For Func
33170 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tions.**.** ^The
33180 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
33190 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 _db_handle() int
331a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
331b0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
331c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
331d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
331e0 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 ion] (the 1st pa
331f0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 rameter).** of t
33200 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
33210 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
33220 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
33230 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
33240 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 ()] routines tha
33250 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 t originally.**
33260 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 registered the a
33270 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
33280 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a ed function..*/.
33290 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 sqlite3 *sqlite3
332a0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
332b0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
332c0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
332d0 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 I3REF: Function
332e0 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a Auxiliary Data.*
332f0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
33300 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 ions may be used
33310 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 by (non-aggrega
33320 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e te) SQL function
33330 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
33340 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
33350 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
33360 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
33370 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
33380 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
33390 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
333a0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
333b0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
333c0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
333d0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
333e0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
333f0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
33400 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 be preserved.
33410 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 An example.** of
33420 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 where this migh
33430 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 t be useful is i
33440 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 n a regular-expr
33450 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a ession matching.
33460 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 ** function. The
33470 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f compiled versio
33480 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 n of the regular
33490 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 expression can
334a0 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 be stored as.**
334b0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 metadata associa
334c0 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74 ted with the pat
334d0 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a tern string. .*
334e0 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 * Then as long a
334f0 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 s the pattern st
33500 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 ring remains the
33510 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f same,.** the co
33520 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 mpiled regular e
33530 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 xpression can be
33540 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 reused on multi
33550 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ple.** invocatio
33560 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 ns of the same f
33570 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e unction..**.** ^
33580 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
33590 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 auxdata() interf
335a0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
335b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 inter to the met
335c0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 adata.** associa
335d0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 ted by the sqlit
335e0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
335f0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 function with t
33600 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a he Nth argument.
33610 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 ** value to the
33620 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
33630 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 ned function. ^I
33640 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 f there is no me
33650 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 tadata.** associ
33660 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75 ated with the fu
33670 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c nction argument,
33680 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 this sqlite3_ge
33690 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
336a0 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 rface.** returns
336b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
336c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
336d0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
336e0 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 C,N,P,X) interfa
336f0 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 ce saves P as me
33700 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e tadata for the N
33710 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 -th.** argument
33720 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
33730 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
33740 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e ion. ^Subsequen
33750 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 t.** calls to sq
33760 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
33770 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 a(C,N) return P
33780 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 from the most re
33790 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cent.** sqlite3_
337a0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
337b0 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 P,X) call if the
337c0 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69 metadata is sti
337d0 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e ll valid or.** N
337e0 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 ULL if the metad
337f0 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 ata has been dis
33800 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 carded..** ^Afte
33810 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 r each call to s
33820 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
33830 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 ta(C,N,P,X) wher
33840 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c e X is not NULL,
33850 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
33860 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
33870 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 uctor function X
33880 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 with parameter
33890 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 P exactly.** onc
338a0 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 e, when the meta
338b0 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65 data is discarde
338c0 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 d..** SQLite is
338d0 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 free to discard
338e0 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 the metadata at
338f0 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 any time, includ
33900 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 ing: <ul>.** <li
33910 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 > when the corre
33920 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f sponding functio
33930 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e n parameter chan
33940 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 ges, or.** <li>
33950 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 when [sqlite3_re
33960 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
33970 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
33980 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 s called for the
33990 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 .** SQL sta
339a0 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c tement, or.** <l
339b0 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f i> when sqlite3_
339c0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 set_auxdata() is
339d0 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f invoked again o
339e0 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d n the same param
339f0 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e eter, or.** <li>
33a00 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 during the orig
33a10 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 inal sqlite3_set
33a20 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 _auxdata() call
33a30 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a when a memory .*
33a40 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f * allocatio
33a50 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 n error occurs.
33a60 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f </ul>)^.**.** No
33a70 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c te the last bull
33a80 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 et in particular
33a90 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f . The destructo
33aa0 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 r X in .** sqlit
33ab0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 e3_set_auxdata(C
33ac0 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 ,N,P,X) might be
33ad0 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 called immediat
33ae0 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a ely, before the.
33af0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 ** sqlite3_set_a
33b00 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
33b10 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e ce even returns.
33b20 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f Hence sqlite3_
33b30 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a set_auxdata().**
33b40 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 should be calle
33b50 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f d near the end o
33b60 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 f the function i
33b70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e mplementation an
33b80 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f d the.** functio
33b90 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
33ba0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 should not make
33bb0 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 any use of P af
33bc0 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ter.** sqlite3_s
33bd0 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 et_auxdata() has
33be0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a been called..**
33bf0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 .** ^(In practic
33c00 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 e, metadata is p
33c10 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e reserved between
33c20 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 function calls
33c30 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 for.** function
33c40 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 parameters that
33c50 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 are compile-time
33c60 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c constants, incl
33c70 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a uding literal.**
33c80 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 values and [par
33c90 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 ameters] and exp
33ca0 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 ressions compose
33cb0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e d from the same.
33cc0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 )^.**.** These r
33cd0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
33ce0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
33cf0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
33d00 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 hich.** the SQL
33d10 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
33d20 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ing..*/.void *sq
33d30 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
33d40 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
33d50 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 t*, int N);.void
33d60 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
33d70 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
33d80 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f text*, int N, vo
33d90 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f id*, void (*)(vo
33da0 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 id*));.../*.** C
33db0 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e API3REF: Constan
33dc0 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 ts Defining Spec
33dd0 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 ial Destructor B
33de0 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 ehavior.**.** Th
33df0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 ese are special
33e00 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 values for the d
33e10 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 estructor that i
33e20 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 s passed in as t
33e30 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 he.** final argu
33e40 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 ment to routines
33e50 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 like [sqlite3_r
33e60 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 esult_blob()].
33e70 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 ^If the destruct
33e80 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 or.** argument i
33e90 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c s SQLITE_STATIC,
33ea0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
33eb0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 he content point
33ec0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a er is constant.*
33ed0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 * and will never
33ee0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 change. It doe
33ef0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
33f00 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 destroyed. ^Th
33f10 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e e.** SQLITE_TRAN
33f20 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e SIENT value mean
33f30 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
33f40 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 nt will likely c
33f50 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 hange in.** the
33f60 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 near future and
33f70 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 that SQLite shou
33f80 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 ld make its own
33f90 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a private copy of.
33fa0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 ** the content b
33fb0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
33fc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 .**.** The typed
33fd0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 ef is necessary
33fe0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 to work around p
33ff0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 roblems in certa
34000 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c in.** C++ compil
34010 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ers..*/.typedef
34020 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 void (*sqlite3_d
34030 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 estructor_type)(
34040 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 void*);.#define
34050 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 SQLITE_STATIC
34060 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 ((sqlite3_des
34070 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a tructor_type)0).
34080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
34090 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c RANSIENT ((sql
340a0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
340b0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 type)-1)../*.**
340c0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e CAPI3REF: Settin
340d0 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 g The Result Of
340e0 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a An SQL Function.
340f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
34100 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 ines are used by
34110 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 the xFunc or xF
34120 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 inal callbacks t
34130 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 hat.** implement
34140 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
34150 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 nd aggregates.
34160 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f See.** [sqlite3_
34170 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
34180 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
34190 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
341a0 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 6()].** for addi
341b0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
341c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 on..**.** These
341d0 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 functions work v
341e0 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 ery much like th
341f0 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e e [parameter bin
34200 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a ding] family of.
34210 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 ** functions use
34220 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 d to bind values
34230 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 to host paramet
34240 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 ers in prepared
34250 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 statements..** R
34260 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c efer to the [SQL
34270 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 parameter] docu
34280 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
34290 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
342a0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tion..**.** ^The
342b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
342c0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 blob() interface
342d0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
342e0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
342f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
34300 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
34310 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f he BLOB whose co
34320 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 ntent is pointed
34330 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 .** to by the se
34340 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 cond parameter a
34350 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 nd which is N by
34360 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e tes long where N
34370 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 is the.** third
34380 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
34390 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
343a0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 esult_zeroblob()
343b0 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 interfaces set
343c0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a the result of.**
343d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
343e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
343f0 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 n to be a BLOB c
34400 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 ontaining all ze
34410 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 ro.** bytes and
34420 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c N bytes in size,
34430 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
34440 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 value of the 2nd
34450 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
34460 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
34470 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 esult_double() i
34480 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
34490 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a e result from.**
344a0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
344b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
344c0 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e to be a floatin
344d0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 g point value sp
344e0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 ecified.** by it
344f0 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a s 2nd argument..
34500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
34510 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
34520 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 ) and sqlite3_re
34530 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 sult_error16() f
34540 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 unctions.** caus
34550 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 e the implemente
34560 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 d SQL function t
34570 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 o throw an excep
34580 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 tion..** ^SQLite
34590 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 uses the string
345a0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 pointed to by t
345b0 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 he.** 2nd parame
345c0 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 ter of sqlite3_r
345d0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 esult_error() or
345e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
345f0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 error16().** as
34600 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 the text of an e
34610 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e rror message. ^
34620 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 SQLite interpret
34630 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
34640 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 essage string fr
34650 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c om sqlite3_resul
34660 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 t_error() as UTF
34670 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 -8. ^SQLite.** i
34680 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 nterprets the st
34690 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 ring from sqlite
346a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
346b0 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 () as UTF-16 in
346c0 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f native.** byte o
346d0 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 rder. ^If the t
346e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
346f0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 o sqlite3_result
34700 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 _error().** or s
34710 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
34720 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 ror16() is negat
34730 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 ive then SQLite
34740 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 takes as the err
34750 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c or.** message al
34760 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 l text up throug
34770 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f h the first zero
34780 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e character..** ^
34790 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
347a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
347b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
347c0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 or.** sqlite3_r
347d0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
347e0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 is non-negative
347f0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 then SQLite take
34800 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 s that many.** b
34810 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 ytes (not charac
34820 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 ters) from the 2
34830 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 nd parameter as
34840 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
34850 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 e..** ^The sqlit
34860 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
34870 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 ) and sqlite3_re
34880 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
34890 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 * routines make
348a0 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f a private copy o
348b0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 f the error mess
348c0 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a age text before.
348d0 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 ** they return.
348e0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c Hence, the call
348f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e ing function can
34900 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a deallocate or.*
34910 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 * modify the tex
34920 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 t after they ret
34930 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d urn without harm
34940 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
34950 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
34960 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 ode() function c
34970 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 hanges the error
34980 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 code.** returne
34990 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 d by SQLite as a
349a0 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 result of an er
349b0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f ror in a functio
349c0 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c n. ^By default,
349d0 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f .** the error co
349e0 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 de is SQLITE_ERR
349f0 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 OR. ^A subseque
34a00 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 nt call to sqlit
34a10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
34a20 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
34a30 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
34a40 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f resets the erro
34a50 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 r code to SQLITE
34a60 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 _ERROR..**.** ^T
34a70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
34a80 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 t_error_toobig()
34a90 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 interface cause
34aa0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f s SQLite to thro
34ab0 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e w an.** error in
34ac0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 dicating that a
34ad0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 string or BLOB i
34ae0 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 s too long to re
34af0 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e present..**.** ^
34b00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
34b10 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 lt_error_nomem()
34b20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 interface cause
34b30 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f s SQLite to thro
34b40 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e w an.** error in
34b50 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 dicating that a
34b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
34b70 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 n failed..**.**
34b80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
34b90 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 ult_int() interf
34ba0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
34bb0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
34bc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
34bd0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
34be0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 to be the 32-bi
34bf0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
34c00 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 .** value given
34c10 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d in the 2nd argum
34c20 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ent..** ^The sql
34c30 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 ite3_result_int6
34c40 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 4() interface se
34c50 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ts the return va
34c60 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 lue.** of the ap
34c70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
34c80 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
34c90 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e the 64-bit sign
34ca0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 ed integer.** va
34cb0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 lue given in the
34cc0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2nd argument..*
34cd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
34ce0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 3_result_null()
34cf0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
34d00 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
34d10 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
34d20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
34d30 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c nction to be NUL
34d40 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 L..**.** ^The sq
34d50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
34d60 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 t(), sqlite3_res
34d70 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a ult_text16(),.**
34d80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34d90 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 text16le(), and
34da0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
34db0 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 ext16be() interf
34dc0 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 aces.** set the
34dd0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
34de0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
34df0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
34e00 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 to be.** a text
34e10 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
34e20 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 represented as
34e30 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 UTF-8, UTF-16 na
34e40 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c tive byte order,
34e50 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c .** UTF-16 littl
34e60 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 e endian, or UTF
34e70 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 -16 big endian,
34e80 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
34e90 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 ^SQLite takes t
34ea0 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 he text result f
34eb0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 rom the applicat
34ec0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 ion from.** the
34ed0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
34ee0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
34ef0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
34f00 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 aces..** ^If the
34f10 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
34f20 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
34f30 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
34f40 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 faces.** is nega
34f50 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 tive, then SQLit
34f60 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 e takes result t
34f70 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 ext from the 2nd
34f80 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 parameter.** th
34f90 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 rough the first
34fa0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a zero character..
34fb0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 ** ^If the 3rd p
34fc0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
34fd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
34fe0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
34ff0 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 ** is non-negati
35000 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 ve, then as many
35010 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 bytes (not char
35020 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 acters) of the t
35030 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 ext.** pointed t
35040 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 o by the 2nd par
35050 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e ameter are taken
35060 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 as the applicat
35070 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 ion-defined.** f
35080 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 unction result.
35090 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
350a0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 meter is non-neg
350b0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a ative, then it.*
350c0 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 * must be the by
350d0 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 te offset into t
350e0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 he string where
350f0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 the NUL terminat
35100 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 or would.** appe
35110 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 ar if the string
35120 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 where NUL termi
35130 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e nated. If any N
35140 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 UL characters oc
35150 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 cur.** in the st
35160 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f ring at a byte o
35170 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 ffset that is le
35180 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 ss than the valu
35190 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 e of the 3rd.**
351a0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 parameter, then
351b0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
351c0 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 ring will contai
351d0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 n embedded NULs
351e0 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c and the.** resul
351f0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
35200 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 operating on st
35210 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 rings with embed
35220 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
35230 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 fined..** ^If th
35240 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
35250 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
35260 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
35270 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
35280 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
35290 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 is a non-NULL p
352a0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
352b0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a ite calls that.*
352c0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 * function as th
352d0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 e destructor on
352e0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
352f0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 result when it
35300 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 has.** finished
35310 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
35320 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 t..** ^If the 4t
35330 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
35340 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
35350 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
35360 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 es or to.** sqli
35370 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
35380 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
35390 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 onstant SQLITE_S
353a0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 TATIC, then SQLi
353b0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 te.** assumes th
353c0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 at the text or B
353d0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e LOB result is in
353e0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 constant space
353f0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 and does not.**
35400 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 copy the content
35410 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 of the paramete
35420 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 r nor call a des
35430 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 tructor on the c
35440 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 ontent.** when i
35450 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 t has finished u
35460 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 sing that result
35470 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 ..** ^If the 4th
35480 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
35490 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
354a0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
354b0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f s.** or sqlite3_
354c0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
354d0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
354e0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ant SQLITE_TRANS
354f0 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c IENT.** then SQL
35500 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
35510 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 of the result i
35520 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e nto space obtain
35530 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 ed from.** from
35540 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
35550 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 )] before it ret
35560 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 urns..**.** ^The
35570 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
35580 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
35590 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
355a0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c t of.** the appl
355b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
355c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
355d0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e copy the.** [un
355e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
355f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
35600 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
35610 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 2nd parameter.
35620 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
35630 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
35640 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
35650 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
35660 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
35670 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
35680 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
35690 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
356a0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
356b0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
356c0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
356d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
356e0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
356f0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 hout harm..** ^A
35700 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
35710 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
35720 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 t may always be
35730 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a used where an.**
35740 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
35750 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
35760 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c ect is required,
35770 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 so either.** ki
35780 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 nd of [sqlite3_v
35790 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e alue] object can
357a0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 be used with th
357b0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
357c0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 .** If these rou
357d0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
357e0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
357f0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
35800 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e d.** than the on
35810 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
35820 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
35830 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 ined function th
35840 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 at received.** t
35850 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
35860 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 ext] pointer, th
35870 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
35880 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 defined..*/.void
35890 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
358a0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e blob(sqlite3_con
358b0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
358c0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
358d0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
358e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
358f0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e uble(sqlite3_con
35900 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a text*, double);.
35910 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
35920 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 ult_error(sqlite
35930 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
35940 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 t char*, int);.v
35950 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
35960 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 lt_error16(sqlit
35970 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
35980 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a st void*, int);.
35990 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
359a0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 ult_error_toobig
359b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
359c0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
359d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f _result_error_no
359e0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 mem(sqlite3_cont
359f0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 ext*);.void sqli
35a00 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
35a10 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f _code(sqlite3_co
35a20 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f ntext*, int);.vo
35a30 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
35a40 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f t_int(sqlite3_co
35a50 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f ntext*, int);.vo
35a60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
35a70 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f t_int64(sqlite3_
35a80 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
35a90 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 3_int64);.void s
35aa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 qlite3_result_nu
35ab0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ll(sqlite3_conte
35ac0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 xt*);.void sqlit
35ad0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 e3_result_text(s
35ae0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
35af0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e const char*, in
35b00 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
35b10 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
35b20 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 _result_text16(s
35b30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
35b40 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
35b50 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
35b60 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
35b70 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
35b80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
35b90 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
35ba0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
35bb0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
35bc0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
35bd0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
35be0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
35bf0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 int,void(*)(voi
35c00 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 d*));.void sqlit
35c10 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
35c20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
35c30 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a , sqlite3_value*
35c40 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
35c50 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
35c60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
35c70 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a , int n);../*.**
35c80 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e CAPI3REF: Defin
35c90 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 e New Collating
35ca0 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 Sequences.**.**
35cb0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
35cc0 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 add, remove, or
35cd0 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 modify a [colla
35ce0 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 tion] associated
35cf0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 .** with the [da
35d00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
35d10 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 n] specified as
35d20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
35d30 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e nt..**.** ^The n
35d40 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 ame of the colla
35d50 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 tion is a UTF-8
35d60 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 string.** for sq
35d70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
35d80 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c lation() and sql
35d90 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
35da0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e ation_v2().** an
35db0 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e d a UTF-16 strin
35dc0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 g in native byte
35dd0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 order for sqlit
35de0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
35df0 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c ion16()..** ^Col
35e00 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 lation names tha
35e10 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 t compare equal
35e20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 according to [sq
35e30 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 lite3_strnicmp()
35e40 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 ] are.** conside
35e50 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 red to be the sa
35e60 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e me name..**.** ^
35e70 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d (The third argum
35e80 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d ent (eTextRep) m
35e90 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 ust be one of th
35ea0 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 e constants:.**
35eb0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
35ec0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c LITE_UTF8],.** <
35ed0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 li> [SQLITE_UTF1
35ee0 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 6LE],.** <li> [S
35ef0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a QLITE_UTF16BE],.
35f00 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
35f10 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c UTF16], or.** <l
35f20 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 i> [SQLITE_UTF16
35f30 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f _ALIGNED]..** </
35f40 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 ul>)^.** ^The eT
35f50 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 extRep argument
35f60 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 determines the e
35f70 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e ncoding of strin
35f80 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 gs passed.** to
35f90 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 the collating fu
35fa0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c nction callback,
35fb0 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e xCallback..** ^
35fc0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 The [SQLITE_UTF1
35fd0 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 6] and [SQLITE_U
35fe0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 TF16_ALIGNED] va
35ff0 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 lues for eTextRe
36000 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e p.** force strin
36010 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 gs to be UTF16 w
36020 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 ith native byte
36030 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b order..** ^The [
36040 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
36050 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 GNED] value for
36060 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 eTextRep forces
36070 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e strings to begin
36080 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 .** on an even b
36090 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a yte address..**.
360a0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 ** ^The fourth a
360b0 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 rgument, pArg, i
360c0 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e s an application
360d0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 data pointer th
360e0 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 at is passed.**
360f0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 through as the f
36100 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
36110 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 the collating f
36120 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b unction callback
36130 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 ..**.** ^The fif
36140 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 th argument, xCa
36150 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 llback, is a poi
36160 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c nter to the coll
36170 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a ating function..
36180 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c ** ^Multiple col
36190 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 lating functions
361a0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 can be register
361b0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d ed using the sam
361c0 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 e name but.** wi
361d0 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 th different eTe
361e0 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 xtRep parameters
361f0 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c and SQLite will
36200 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a use whichever.*
36210 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 * function requi
36220 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d res the least am
36230 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 ount of data tra
36240 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 nsformation..**
36250 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 ^If the xCallbac
36260 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 k argument is NU
36270 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c LL then the coll
36280 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 ating function i
36290 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e s.** deleted. ^
362a0 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 When all collati
362b0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 ng functions hav
362c0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ing the same nam
362d0 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a e are deleted,.*
362e0 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e * that collation
362f0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 is no longer us
36300 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 able..**.** ^The
36310 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
36320 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ion callback is
36330 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 invoked with a c
36340 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 opy of the pArg
36350 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 .** application
36360 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 data pointer and
36370 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 with two string
36380 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e s in the encodin
36390 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 g specified.** b
363a0 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 y the eTextRep a
363b0 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f rgument. The co
363c0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
363d0 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a must return an.
363e0 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 ** integer that
363f0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 is negative, zer
36400 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a o, or positive.*
36410 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 * if the first s
36420 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 tring is less th
36430 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 an, equal to, or
36440 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 greater than th
36450 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 e second,.** res
36460 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f pectively. A co
36470 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
36480 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 must always ret
36490 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 urn the same ans
364a0 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 wer.** given the
364b0 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 same inputs. I
364c0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f f two or more co
364d0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
364e0 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 s are registered
364f0 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 .** to the same
36500 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 collation name (
36510 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 using different
36520 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 eTextRep values)
36530 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 then all.** mus
36540 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 t give an equiva
36550 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e lent answer when
36560 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 invoked with eq
36570 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 uivalent strings
36580 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 ..** The collati
36590 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ng function must
365a0 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 obey the follow
365b0 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 ing properties f
365c0 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 or all.** string
365d0 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a s A, B, and C:.*
365e0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
365f0 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 > If A==B then B
36600 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 ==A..** <li> If
36610 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 A==B and B==C th
36620 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e en A==C..** <li>
36630 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 If A<B THEN
36640 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 B>A..** <li>
36650 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 If A<B and B&
36660 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 lt;C then A<C
36670 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a ..** </ol>.**.**
36680 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 If a collating
36690 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 function fails a
366a0 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 ny of the above
366b0 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 constraints and
366c0 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e that.** collatin
366d0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 g function is r
366e0 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 egistered and us
366f0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 ed, then the beh
36700 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a avior of SQLite.
36710 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e ** is undefined.
36720 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36730 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
36740 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 tion_v2() works
36750 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 like sqlite3_cre
36760 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a ate_collation().
36770 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 ** with the addi
36780 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 tion that the xD
36790 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 estroy callback
367a0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 is invoked on pA
367b0 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 rg when.** the c
367c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
367d0 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a n is deleted..**
367e0 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 ^Collating func
367f0 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 tions are delete
36800 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 d when they are
36810 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 overridden by la
36820 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ter.** calls to
36830 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 the collation cr
36840 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 eation functions
36850 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 or when the.**
36860 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
36870 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 tion] is closed
36880 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
36890 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e lose()]..**.** ^
368a0 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c The xDestroy cal
368b0 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c lback is <u>not<
368c0 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 /u> called if th
368d0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 e .** sqlite3_cr
368e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
368f0 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 2() function fai
36900 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ls. Application
36910 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a s that invoke.**
36920 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
36930 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 collation_v2() w
36940 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 ith a non-NULL x
36950 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 Destroy argument
36960 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 should .** chec
36970 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 k the return cod
36980 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 e and dispose of
36990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
369a0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a data pointer.**
369b0 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 themselves rath
369c0 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e er than expectin
369d0 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c g SQLite to deal
369e0 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 with it for the
369f0 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 m..** This is di
36a00 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 fferent from eve
36a10 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ry other SQLite
36a20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 interface. The
36a30 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a inconsistency .*
36a40 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 * is unfortunate
36a50 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 but cannot be c
36a60 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 hanged without b
36a70 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 reaking backward
36a80 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c s .** compatibil
36a90 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ity..**.** See a
36aa0 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 lso: [sqlite3_c
36ab0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
36ac0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
36ad0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
36ae0 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 16()]..*/.int sq
36af0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
36b00 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 lation(. sqlite
36b10 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 3*, . const cha
36b20 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 r *zName, . int
36b30 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f eTextRep, . vo
36b40 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 id *pArg,. int(
36b50 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
36b60 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
36b70 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
36b80 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
36b90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
36ba0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a n_v2(. sqlite3*
36bb0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 , . const char
36bc0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 *zName, . int e
36bd0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
36be0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 *pArg,. int(*x
36bf0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 Compare)(void*,i
36c00 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 nt,const void*,i
36c10 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c nt,const void*),
36c20 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f . void(*xDestro
36c30 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 y)(void*).);.int
36c40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
36c50 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 collation16(. s
36c60 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 qlite3*, . cons
36c70 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 t void *zName,.
36c80 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a int eTextRep, .
36c90 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 void *pArg,.
36ca0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 int(*xCompare)(v
36cb0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
36cc0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
36cd0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid*).);../*.**
36ce0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 CAPI3REF: Collat
36cf0 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 ion Needed Callb
36d00 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 acks.**.** ^To a
36d10 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 void having to r
36d20 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c egister all coll
36d30 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
36d40 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 before a databas
36d50 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 e.** can be used
36d60 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 , a single callb
36d70 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 ack function may
36d80 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 be registered w
36d90 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 ith the.** [data
36da0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
36db0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
36dc0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 henever an undef
36dd0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a ined collation.*
36de0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 * sequence is re
36df0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 quired..**.** ^I
36e00 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 f the function i
36e10 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 s registered usi
36e20 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 ng the sqlite3_c
36e30 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
36e40 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 ) API,.** then i
36e50 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 t is passed the
36e60 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e names of undefin
36e70 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ed collation seq
36e80 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 uences as string
36e90 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 s.** encoded in
36ea0 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 UTF-8. ^If sqlit
36eb0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
36ec0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c ded16() is used,
36ed0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 .** the names ar
36ee0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d e passed as UTF-
36ef0 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 16 in machine na
36f00 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
36f10 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 .** ^A call to e
36f20 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 ither function r
36f30 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 eplaces the exis
36f40 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e ting collation-n
36f50 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a eeded callback..
36f60 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 **.** ^(When the
36f70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
36f80 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 oked, the first
36f90 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
36fa0 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 is a copy.** of
36fb0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
36fc0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ent to sqlite3_c
36fd0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
36fe0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
36ff0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
37000 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 16(). The secon
37010 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
37020 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f e database.** co
37030 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 nnection. The t
37040 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
37050 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
37060 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 UTF8], [SQLITE_U
37070 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b TF16BE],.** or [
37080 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c SQLITE_UTF16LE],
37090 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 indicating the
370a0 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 most desirable f
370b0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 orm of the colla
370c0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
370d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
370e0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 ed. The fourth
370f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
37100 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 name of the.**
37110 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 required collati
37120 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a on sequence.)^.*
37130 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 *.** The callbac
37140 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c k function shoul
37150 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 d register the d
37160 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e esired collation
37170 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
37180 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
37190 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 ion()], [sqlite3
371a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
371b0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
371c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
371d0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a llation_v2()]..*
371e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
371f0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a llation_needed(.
37200 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 sqlite3*, . v
37210 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 oid*, . void(*)
37220 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c (void*,sqlite3*,
37230 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e int eTextRep,con
37240 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 st char*).);.int
37250 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
37260 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 on_needed16(. s
37270 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 qlite3*, . void
37280 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 *,. void(*)(voi
37290 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 d*,sqlite3*,int
372a0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 eTextRep,const v
372b0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 oid*).);..#ifdef
372c0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 SQLITE_HAS_CODE
372d0 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 C./*.** Specify
372e0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 the key for an e
372f0 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 ncrypted databas
37300 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 e. This routine
37310 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 should be.** ca
37320 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 lled right after
37330 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e sqlite3_open().
37340 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
37350 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 to implement thi
37360 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 s API is not ava
37370 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 ilable in the pu
37380 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 blic release.**
37390 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e of SQLite..*/.in
373a0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 t sqlite3_key(.
373b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
373c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
373d0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 /* Database to b
373e0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 e rekeyed */. c
373f0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c onst void *pKey,
37400 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a int nKey /*
37410 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 The key */.);.i
37420 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 nt sqlite3_key_v
37430 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
37440 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
37450 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
37460 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f to be rekeyed */
37470 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
37480 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 DbName,
37490 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
374a0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
374b0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c onst void *pKey,
374c0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a int nKey /*
374d0 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a The key */.);..
374e0 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 /*.** Change the
374f0 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 key on an open
37500 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 database. If th
37510 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 e current databa
37520 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 se is not.** enc
37530 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 rypted, this rou
37540 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 tine will encryp
37550 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d t it. If pNew==
37560 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 0 or nNew==0, th
37570 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 e.** database is
37580 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a decrypted..**.*
37590 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d * The code to im
375a0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 plement this API
375b0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c is not availabl
375c0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 e in the public
375d0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 release.** of SQ
375e0 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c Lite..*/.int sql
375f0 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 ite3_rekey(. sq
37600 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
37610 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
37620 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 Database to be r
37630 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 ekeyed */. cons
37640 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e t void *pKey, in
37650 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 t nKey /* Th
37660 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a e new key */.);.
37670 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 int sqlite3_reke
37680 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 y_v2(. sqlite3
37690 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
376a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
376b0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 se to be rekeyed
376c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
376d0 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 *zDbName,
376e0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
376f0 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a the database */.
37700 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b const void *pK
37710 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 ey, int nKey
37720 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 /* The new key
37730 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 */.);../*.** Spe
37740 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 cify the activat
37750 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 ion key for a SE
37760 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c E database. Unl
37770 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 ess .** activate
37780 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 d, none of the S
37790 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c EE routines will
377a0 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 work..*/.void s
377b0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f qlite3_activate_
377c0 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 see(. const cha
377d0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 r *zPassPhrase
377e0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 /* Activat
377f0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b ion phrase */.);
37800 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 .#endif..#ifdef
37810 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 SQLITE_ENABLE_CE
37820 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 ROD./*.** Specif
37830 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e y the activation
37840 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 key for a CEROD
37850 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 database. Unle
37860 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 ss .** activated
37870 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 , none of the CE
37880 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c ROD routines wil
37890 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 l work..*/.void
378a0 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 sqlite3_activate
378b0 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 _cerod(. const
378c0 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 char *zPassPhras
378d0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 e /* Acti
378e0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f vation phrase */
378f0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a .);.#endif../*.*
37900 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 * CAPI3REF: Susp
37910 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f end Execution Fo
37920 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a r A Short Time.*
37930 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
37940 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f _sleep() functio
37950 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 n causes the cur
37960 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 rent thread to s
37970 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e uspend execution
37980 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 .** for at least
37990 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c a number of mil
379a0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 liseconds specif
379b0 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d ied in its param
379c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 eter..**.** If t
379d0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
379e0 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 tem does not sup
379f0 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 port sleep reque
37a00 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c sts with.** mill
37a10 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 isecond time res
37a20 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 olution, then th
37a30 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 e time will be r
37a40 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 ounded up to.**
37a50 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f the nearest seco
37a60 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f nd. The number o
37a70 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f f milliseconds o
37a80 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 f sleep actually
37a90 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 .** requested fr
37aa0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 om the operating
37ab0 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 system is retur
37ac0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 ned..**.** ^SQLi
37ad0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 te implements th
37ae0 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 is interface by
37af0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 calling the xSle
37b00 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f ep().** method o
37b10 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 f the default [s
37b20 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
37b30 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 ct. If the xSle
37b40 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f ep() method.** o
37b50 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 f the default VF
37b60 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 S is not impleme
37b70 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 nted correctly,
37b80 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 or not implement
37b90 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 ed at.** all, th
37ba0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
37bb0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 of sqlite3_sleep
37bc0 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 () may deviate f
37bd0 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 rom the descript
37be0 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 ion.** in the pr
37bf0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 evious paragraph
37c00 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
37c10 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 3_sleep(int);../
37c20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
37c30 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 ame Of The Folde
37c40 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 r Holding Tempor
37c50 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 ary Files.**.**
37c60 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c ^(If this global
37c70 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 variable is mad
37c80 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 e to point to a
37c90 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a string which is.
37ca0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 ** the name of a
37cb0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 folder (a.k.a.
37cc0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e directory), then
37cd0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 all temporary f
37ce0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 iles.** created
37cf0 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 by SQLite when u
37d00 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 sing a built-in
37d10 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 [sqlite3_vfs | V
37d20 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 FS].** will be p
37d30 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 laced in that di
37d40 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 rectory.)^ ^If
37d50 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a this variable.**
37d60 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
37d70 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
37d80 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 performs a searc
37d90 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 h for an appropr
37da0 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 iate.** temporar
37db0 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 y file directory
37dc0 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ..**.** Applicat
37dd0 69 6f 6e 73 20 61 72 65 20 73 74 72 6f 6e 67 6c ions are strongl
37de0 79 20 64 69 73 63 6f 75 72 61 67 65 64 20 66 72 y discouraged fr
37df0 6f 6d 20 75 73 69 6e 67 20 74 68 69 73 20 67 6c om using this gl
37e00 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 2e 0a 2a obal variable..*
37e10 2a 20 49 74 20 69 73 20 72 65 71 75 69 72 65 64 * It is required
37e20 20 74 6f 20 73 65 74 20 61 20 74 65 6d 70 6f 72 to set a tempor
37e30 61 72 79 20 66 6f 6c 64 65 72 20 6f 6e 20 57 69 ary folder on Wi
37e40 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 28 57 ndows Runtime (W
37e50 69 6e 52 54 29 2e 0a 2a 2a 20 42 75 74 20 66 6f inRT)..** But fo
37e60 72 20 61 6c 6c 20 6f 74 68 65 72 20 70 6c 61 74 r all other plat
37e70 66 6f 72 6d 73 2c 20 69 74 20 69 73 20 68 69 67 forms, it is hig
37e80 68 6c 79 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 hly recommended
37e90 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
37ea0 73 0a 2a 2a 20 6e 65 69 74 68 65 72 20 72 65 61 s.** neither rea
37eb0 64 20 6e 6f 72 20 77 72 69 74 65 20 74 68 69 73 d nor write this
37ec0 20 76 61 72 69 61 62 6c 65 2e 20 20 54 68 69 73 variable. This
37ed0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 global variable
37ee0 20 69 73 20 61 20 72 65 6c 69 63 0a 2a 2a 20 74 is a relic.** t
37ef0 68 61 74 20 65 78 69 73 74 73 20 66 6f 72 20 62 hat exists for b
37f00 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
37f10 62 69 6c 69 74 79 20 6f 66 20 6c 65 67 61 63 79 bility of legacy
37f20 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e applications an
37f30 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 d should.** be a
37f40 76 6f 69 64 65 64 20 69 6e 20 6e 65 77 20 70 72 voided in new pr
37f50 6f 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 ojects..**.** It
37f60 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
37f70 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 read or modify t
37f80 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 his variable in
37f90 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a more than one.**
37fa0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d thread at a tim
37fb0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 e. It is not sa
37fc0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f fe to read or mo
37fd0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 dify this variab
37fe0 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 le.** if a [data
37ff0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
38000 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 is being used a
38010 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 t the same time
38020 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a in a separate.**
38030 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 thread..** It i
38040 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 s intended that
38050 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 this variable be
38060 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 set once.** as
38070 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 part of process
38080 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 initialization a
38090 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 nd before any SQ
380a0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a Lite interface.*
380b0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 * routines have
380c0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 been called and
380d0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
380e0 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e le remain unchan
380f0 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 ged.** thereafte
38100 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 r..**.** ^The [t
38110 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
38120 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 ory pragma] may
38130 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 modify this vari
38140 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a able and cause.*
38150 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f * it to point to
38160 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
38170 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
38180 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 alloc]. ^Furthe
38190 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 rmore,.** the [t
381a0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
381b0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 ory pragma] alwa
381c0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 ys assumes that
381d0 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 any string.** th
381e0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 at this variable
381f0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 points to is he
38200 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 ld in memory obt
38210 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b ained from .** [
38220 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 sqlite3_malloc]
38230 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d and the pragma m
38240 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 ay attempt to fr
38250 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a ee that memory.*
38260 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
38270 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 _free]..** Hence
38280 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 , if this variab
38290 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 le is modified d
382a0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 irectly, either
382b0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 it should be.**
382c0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 made NULL or mad
382d0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 e to point to me
382e0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
382f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
38300 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 oc].** or else t
38310 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 he use of the [t
38320 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
38330 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 ory pragma] shou
38340 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a ld be avoided..*
38350 2a 20 45 78 63 65 70 74 20 77 68 65 6e 20 72 65 * Except when re
38360 71 75 65 73 74 65 64 20 62 79 20 74 68 65 20 5b quested by the [
38370 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
38380 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 53 51 tory pragma], SQ
38390 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 Lite.** does not
383a0 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 free the memory
383b0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 74 65 that sqlite3_te
383c0 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 70 6f 69 mp_directory poi
383d0 6e 74 73 20 74 6f 2e 20 20 49 66 0a 2a 2a 20 74 nts to. If.** t
383e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 he application w
383f0 61 6e 74 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 ants that memory
38400 20 74 6f 20 62 65 20 66 72 65 65 64 2c 20 69 74 to be freed, it
38410 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 73 6f 20 69 must do.** so i
38420 74 73 65 6c 66 2c 20 74 61 6b 69 6e 67 20 63 61 tself, taking ca
38430 72 65 20 74 6f 20 6f 6e 6c 79 20 64 6f 20 73 6f re to only do so
38440 20 61 66 74 65 72 20 61 6c 6c 20 5b 64 61 74 61 after all [data
38450 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
38460 0a 2a 2a 20 6f 62 6a 65 63 74 73 20 68 61 76 65 .** objects have
38470 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e been destroyed.
38480 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 .**.** <b>Note t
38490 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d o Windows Runtim
384a0 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 e users:</b> Th
384b0 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 e temporary dire
384c0 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 ctory must be se
384d0 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 t.** prior to ca
384e0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f lling [sqlite3_o
384f0 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 pen] or [sqlite3
38500 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 _open_v2]. Othe
38510 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a rwise, various.*
38520 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 * features that
38530 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 require the use
38540 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c of temporary fil
38550 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 es may fail. He
38560 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d re is an.** exam
38570 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f ple of how to do
38580 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 this using C++
38590 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 with the Windows
385a0 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 Runtime:.**.**
385b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
385c0 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 >.** LPCWSTR zPa
385d0 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 th = Windows::St
385e0 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 orage::Applicati
385f0 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d onData::Current-
38600 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 >.**
38610 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d TemporaryFolder-
38620 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a >Path->Data();.*
38630 2a 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 * char zPathBuf&
38640 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 #91;MAX_PATH + 1
38650 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 ];.** memset
38660 28 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 (zPathBuf, 0, si
38670 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b zeof(zPathBuf));
38680 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 .** WideCharToMu
38690 6c 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c ltiByte(CP_UTF8,
386a0 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 0, zPath, -1, z
386b0 50 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 PathBuf, sizeof(
386c0 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e zPathBuf),.** &n
386d0 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e bsp; NULL, N
386e0 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 ULL);.** sqlite3
386f0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 _temp_directory
38700 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 = sqlite3_mprint
38710 66 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 f("%s", zPathBuf
38720 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
38730 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c ockquote>.*/.SQL
38740 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 ITE_EXTERN char
38750 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 *sqlite3_temp_di
38760 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 rectory;../*.**
38770 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f CAPI3REF: Name O
38780 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c f The Folder Hol
38790 64 69 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 ding Database Fi
387a0 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 les.**.** ^(If t
387b0 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 his global varia
387c0 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 ble is made to p
387d0 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 oint to a string
387e0 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 which is.** the
387f0 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 name of a folde
38800 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 r (a.k.a. direct
38810 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64 ory), then all d
38820 61 74 61 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a atabase files.**
38830 20 73 70 65 63 69 66 69